Code Harness

A simple coding agent CLI built with AWS Strands SDK — designed as a teaching example of how to build a coding harness from scratch.

There is a complete writeup on my Serverless DNA blog here

What is this?

This is a minimal but functional AI coding assistant that runs in your terminal. You type a request (e.g. "create a Python fibonacci function"), and the agent reads files, writes code, and runs commands to fulfill it.

The agent streams its output in real-time and shows its thinking process as it works, giving you visibility into how it makes decisions.

The entire implementation is ~375 lines of TypeScript across two files.

Architecture

┌─────────┐        ┌───────────┐        ┌─────────────┐
│  User   │ ─────▶ │   Agent   │ ─────▶ │    Tools    │
│ (stdin) │ ◀───── │  (Strands)│ ◀◀──── │  (fs/shell) │
└─────────┘        └─────▲─────┘        └─────────────┘
                         │  │
                    send  │  │ respond
                    msg   │  │ + tool calls
                         │  ▼
                   ┌───────────┐
                   │  Bedrock  │
                   │  (Claude) │
                   └───────────┘

A single user message can trigger multiple LLM ↔ tool round-trips before you see a final response. That multi-turn cycle — running automatically inside agent.stream() — is what makes this an agent rather than a plain chatbot.

How the Agent Loop Works

This is the most important thing to understand. When you call agent.stream(userInput), Strands runs this cycle internally — potentially many times — before yielding your final answer:

  ┌──────────────────────────────────────────────────────────────┐
  │                    agent.stream(userInput)                   │
  │                                                              │
  │  1. Your message is sent to the LLM (Claude on Bedrock)      │
  │                                                              │
  │  2. The LLM streams back a response containing:              │
  │       • reasoning text  →  you see: reasoningContentDelta    │
  │       • response text   →  you see: textDelta events         │
  │       • tool call(s)    →  you see: toolUseStart events      │
  │                                                              │
  │  3. If the LLM requested tool calls, Strands executes them:  │
  │       • runs your callback functions (read file, run cmd…)   │
  │       • you see: toolResultBlock events                      │
  │                                                              │
  │  4. The tool results are sent back to the LLM as a new       │
  │     message, and the LLM responds again  (back to step 2)    │
  │                                                              │
  │  5. The loop ends when the LLM returns a response with       │
  │     no tool calls — meaning it has enough information        │
  │     to give you a final answer.                              │
  └──────────────────────────────────────────────────────────────┘

Example: You ask "add tests to my utils file". The agent might:

Call list_directory to explore the project → LLM sees the result
Call read_file on utils.ts → LLM sees the file contents
Call read_file on the existing test file → LLM sees the test structure
Call write_file to write the new tests → LLM sees the confirmation
Call run_command to run the test suite → LLM sees the output
Return a final text response summarising what it did

All of that happens inside a single agent.stream() call. You didn't orchestrate any of it — the LLM decided which tools to call and in what order.

Features

Real-time streaming — See the agent's response as it's generated
Extended thinking — The model reasons internally before responding (shown in gray text)
Tool visibility — See which tools are being used in real-time
Conversation memory — The agent remembers the full conversation history
Simple configuration — One JSON file with AWS credentials and model settings

Project Structure

src/
├── index.ts          # CLI entry point — agent setup + interactive loop
└── tools.ts          # Four coding tools the agent can use
config.json.example   # Template config — copy to config.json and fill in your settings
build-sea.sh          # Shell script to build the SEA binary
sea-config.json       # Node.js SEA configuration

The Tools

Tool	What it does
`read_file`	Read file contents from disk
`write_file`	Create or overwrite files
`list_directory`	List files/folders in a directory
`run_command`	Execute a shell command (with timeout)

That's it. These four tools are enough for an agent to read code, write code, and verify its work.

Setup

Prerequisites

Node.js 20+
An AWS account with Bedrock model access enabled
AWS CLI installed

1. Configure AWS Authentication

The agent uses AWS credentials to call Bedrock. How you get those credentials depends on your setup — pick the method that matches your situation.

Install AWS CLI

# macOS
brew install awscli

# Linux
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Windows — download and run:
# https://awscli.amazonaws.com/AWSCLIV2.msi

Option A — AWS SSO (recommended for organisations)

If your company uses AWS SSO / IAM Identity Center:

# First-time setup: configure the SSO profile
aws configure sso

# Then log in whenever your session expires
aws sso login --profile your-profile

This stores temporary credentials under the profile name you chose. Use that same name in config.json (see step 3).

Option B — Static credentials (personal AWS account)

If you have a personal AWS account with an IAM user:

aws configure

This prompts for your access key ID, secret access key, and default region, and stores them in ~/.aws/credentials under [default].

What your credentials file looks like

After authenticating, ~/.aws/credentials will contain something like:

[default]
aws_access_key_id = AKIA...          # permanent key (Option B)
aws_secret_access_key = ...

[my-sso-profile]
aws_access_key_id = ASIA...          # temporary key — notice the ASIA prefix
aws_secret_access_key = ...
aws_session_token = IQoJb3JpZ2lu...  # session token required for temporary creds

Temporary credentials (SSO / STS) expire after 1–12 hours depending on your organisation's settings. When they expire, run aws sso login again.

2. Enable Model Access in Bedrock

Go to the AWS Bedrock console → Model access → Request access to the models you want to use.

3. Configure the Agent

Copy the example config and fill in your settings:

cp config.json.example config.json

Then edit config.json:

{
  "aws_profile": "default",
  "aws_region": "us-east-1",
  "model_id": "global.anthropic.claude-sonnet-4-6",
  "thinking_budget_tokens": 5000
}

Field	Description
`aws_profile`	The AWS CLI profile name to use (`default`, or a named profile like `my-sso-profile`)
`aws_region`	AWS region where Bedrock is available
`model_id`	The Bedrock model identifier
`max_tokens`	(optional) Maximum tokens in the model's response. Defaults to `16,000` when thinking is enabled.
`thinking_budget_tokens`	(optional) How many tokens the model can spend on internal reasoning. Set to `0` to disable thinking. Defaults to `5000`.

Note: temperature is not a config option here — when thinking is enabled the Anthropic API requires temperature: 1 exactly, so it is set automatically. When thinking is disabled, 0.3 is used. See the walkthrough below for details.

Available Models on Bedrock

Extended thinking requires Claude Sonnet 4 or newer. Older models (Sonnet 3.5, Haiku) will ignore the thinking config or return an error.

🟣 Anthropic — Claude

Model	ID	Thinking
Claude Sonnet 4.6 (default)	`global.anthropic.claude-sonnet-4-6`	✅
Claude Sonnet 4	`anthropic.claude-sonnet-4-20250514-v1:0`	✅
Claude Sonnet 3.5 v2	`anthropic.claude-3-5-sonnet-20241022-v2:0`	❌
Claude Haiku 3.5	`anthropic.claude-3-5-haiku-20241022-v1:0`	❌

If you switch to a model that doesn't support thinking, set thinking_budget_tokens to 0 in config.json.

🔵 Zhipu AI — GLM

Model	ID	Notes
GLM-4	`zhipu.glm-4`	Flagship GLM model — strong at reasoning & code
GLM-4V	`zhipu.glm-4v`	Multimodal variant with vision support

Note: GLM models are available via Bedrock in supported regions. Check the Bedrock model catalog for availability in your region.

🟢 Alibaba — Qwen

Model	ID	Notes
Qwen 2.5 72B Instruct	`qwen.qwen2-5-72b-instruct`	Latest flagship Qwen — top-tier reasoning & coding
Qwen 2.5 Coder 32B	`qwen.qwen2-5-coder-32b-instruct`	Specialized for code generation & completion
Qwen 2.5 7B Instruct	`qwen.qwen2-5-7b-instruct`	Lightweight, fast, cost-effective

Note: Qwen models are available via Bedrock Marketplace. Check the Bedrock model catalog for availability and subscription requirements.

4. Environment Variable Overrides

You can override any config value with environment variables (useful for CI or switching between profiles quickly):

# Override the profile
AWS_PROFILE=my-other-profile npm run dev

# Override the region
AWS_REGION=eu-west-1 npm run dev

# Override the model (disable thinking if switching to a non-Claude-4 model)
MODEL_ID=anthropic.claude-3-5-haiku-20241022-v1:0 npm run dev

# Use Qwen instead of Claude
MODEL_ID=qwen.qwen2-5-72b-instruct npm run dev

# Combine overrides
AWS_PROFILE=prod AWS_REGION=us-west-2 npm run dev

Priority order: Environment variable > config.json value

5. Install & Run

npm install
npm run dev

You should see:

🔧 Code Harness — a simple coding agent
   Model:    global.anthropic.claude-sonnet-4-6
   Region:   us-east-1
   Profile:  default
   Thinking: enabled (budget: 5000 tokens)
   Type your request and press Enter. Type 'exit' to quit.

>

As the agent works, you'll see:

Gray text — The model's internal reasoning (thinking), streamed before the response
Cyan text — Tool usage notifications (e.g., [Using tool: read_file])
Normal text — The agent's final response to you

Building a Standalone Binary (SEA)

You can compile the entire agent into a single executable — no Node.js installation required to run it:

./build-sea.sh

This produces dist/code-harness (~115MB, includes the Node.js runtime). Copy it anywhere and run:

./dist/code-harness

Note: The binary still reads config.json from the current working directory at runtime. Make sure the config file is present and that you have valid AWS credentials.

How the SEA build works:

Bundle — esbuild compiles all TypeScript + dependencies into one dist/bundle.js file
Generate blob — node --experimental-sea-config creates a binary blob from the bundle
Inject — The blob is injected into a copy of the node binary using postject
Sign — On macOS, the binary is re-signed with an ad-hoc signature

See build-sea.sh for the full process (~50 lines of bash).

How It Works — A Walkthrough

1. Loading Config & Creating the Model (`src/index.ts`)

import { Agent, BedrockModel } from "@strands-agents/sdk";

const config = loadConfig();
process.env.AWS_PROFILE = config.aws_profile;

const thinkingBudget = config.thinking_budget_tokens ?? 5000;
const thinkingEnabled = thinkingBudget > 0;

// When thinking is on, Anthropic requires max_tokens > budget_tokens.
// We default to 16,000 which gives the model plenty of room to write
// large files or long responses after spending its thinking budget.
const DEFAULT_MAX_TOKENS_WITH_THINKING = 16000;

const model = new BedrockModel({
  region: config.aws_region,
  modelId: config.model_id,
  // Anthropic requires temperature: 1 when thinking is enabled.
  temperature: thinkingEnabled ? 1 : 0.3,
  // When thinking is off: leave maxTokens unset so Bedrock uses the model's
  // own maximum. When thinking is on: we must provide a value greater than
  // budget_tokens — Anthropic rejects the request otherwise.
  maxTokens: config.max_tokens ?? (thinkingEnabled ? DEFAULT_MAX_TOKENS_WITH_THINKING : undefined),
  // Thinking is passed via additionalRequestFields — there is no dedicated
  // thinking option on BedrockModel. This maps to Bedrock's
  // additionalModelRequestFields and is forwarded to the API as-is.
  ...(thinkingEnabled && {
    additionalRequestFields: {
      thinking: {
        type: "enabled",
        budget_tokens: thinkingBudget,
      },
    },
  }),
});

The BedrockModel uses the standard AWS SDK credential chain. By setting AWS_PROFILE, the SDK automatically loads credentials from ~/.aws/credentials for that profile — whether they're permanent keys or temporary STS tokens.

How thinking works in Strands

Strands has no dedicated thinking: true flag. Extended thinking is enabled by passing the thinking config through additionalRequestFields, which BedrockModel forwards directly to Bedrock's additionalModelRequestFields on every request.

Two hard requirements from Anthropic when thinking is on:

temperature must be exactly 1 — any other value is rejected by the API
max_tokens must exceed budget_tokens — the budget is consumed first, then the response is generated within the remaining token allowance

When thinking is enabled, the model reasons internally before writing its response. That reasoning is streamed back as reasoningContentDelta events, which we display in gray text. The thinking content is also included in the conversation history so the model can refer back to its earlier reasoning on follow-up turns.

2. Defining Tools (`src/tools.ts`)

Each tool uses the Strands tool() helper with a Zod schema:

import { tool } from "@strands-agents/sdk";
import { z } from "zod";

const readFile = tool({
  name: "read_file",
  description: "Read the contents of a file at the given path. Returns the file text.",
  inputSchema: z.object({
    filePath: z.string().describe("Path to the file to read (relative or absolute)"),
  }),
  callback: (input) => {
    return fs.readFileSync(input.filePath, "utf-8");
  },
});

Three things make a tool:

description — the LLM reads this to decide when to call the tool. Write it clearly.
inputSchema — a Zod schema that defines what arguments the LLM must provide. Strands validates the LLM's output against this before calling your function.
callback — the function that actually runs when the tool is called. Whatever it returns is sent back to the LLM as the tool result.

The LLM never calls your code directly. It emits a structured tool_use block in its response (e.g. { name: "read_file", input: { filePath: "src/index.ts" } }), and Strands is the one that validates it, calls your callback, and feeds the result back.

3. Creating the Agent

const agent = new Agent({
  model,                         // Bedrock provider
  systemPrompt: SYSTEM_PROMPT,   // Personality & instructions
  tools: codingTools,            // What it can do
});

The agent maintains conversation history automatically across stream() calls. We handle streaming output ourselves in the loop below, so we can display thinking in gray text and tool calls in cyan.

4. The Streaming Loop

This is where Strands does its work. A single call to agent.stream() runs the full multi-turn agent loop and surfaces each step as a typed event:

for await (const event of agent.stream(userInput)) {

  // Token-by-token streaming deltas — text output and thinking output.
  if (event.type === "modelContentBlockDeltaEvent") {
    const { delta } = event;

    if (delta.type === "textDelta") {
      // A chunk of the LLM's text response — print as it arrives.
      process.stdout.write(delta.text);

    } else if (delta.type === "reasoningContentDelta" && delta.text) {
      // The LLM's internal reasoning — shown in dim/italic gray.
      // Only fires when thinking is enabled in the model config.
      process.stdout.write(`\x1b[2m\x1b[3m${delta.text}\x1b[0m`);
    }

  // The LLM has decided to call a tool. Fires BEFORE the tool runs.
  // event.start.name = tool name.
  } else if (event.type === "modelContentBlockStartEvent") {
    if (event.start?.type === "toolUseStart") {
      process.stdout.write(`\n\x1b[36m[Using tool: ${event.start.name}]\x1b[0m\n`); // cyan
    }

  // The tool has finished running. Fires AFTER the callback returns.
  // Strands automatically sends this result back to the LLM.
  } else if (event.type === "toolResultBlock") {
    if (event.status === "error") {
      console.log(`\x1b[31m[Tool error]\x1b[0m`);
    }
  }
}

Event order within a single agent.stream() call (the tool section may repeat many times):

reasoningContentDelta  →  toolUseStart  →  toolResultBlock  →  (repeat)  →  final textDelta

You don't call the LLM again yourself. You don't collect tool results and pass them back. Strands handles all of that — the for await loop just keeps yielding events until the agent is done.

Key Concepts for Learners

Tools are just functions — There's no magic. A tool is a function with a name, description, and typed inputs. The LLM reads the descriptions and decides which ones to call.
The LLM doesn't run your code — Strands does — The LLM emits a structured tool call request. Strands validates it against your Zod schema, runs your callback, and sends the result back to the LLM. Your function is never called directly by the model.
agent.stream() is the whole agent loop — One call can trigger many LLM ↔ tool round-trips. The loop ends automatically when the LLM stops requesting tools and returns a plain text response.
Thinking has no dedicated flag — use additionalRequestFields — Strands passes additionalRequestFields directly to Bedrock's additionalModelRequestFields. This is the correct way to enable any model feature that isn't a first-class SDK option, including thinking.
Streaming shows the process — Unlike invoke() which only returns the final result, stream() lets you observe each step: reasoning, tool calls, tool results, and the final answer — all as they happen.
The system prompt matters — It shapes how the agent behaves. Our prompt tells it to read before writing and to test its changes. The LLM follows these instructions when deciding which tools to call and in what order.
Conversation memory is built-in — The agent maintains the full message history across stream() calls. Each turn appends to that history, so the LLM always has context from earlier in the session.

Troubleshooting

Error	Fix
`config.json not found`	Copy `config.json.example` to `config.json` and fill in your settings
`AccessDeniedException`	Your profile doesn't have Bedrock permissions, or credentials have expired — re-authenticate with `aws sso login`
`ResourceNotFoundException`	The model ID is wrong or not available in your region
`ValidationException` (model access)	Enable model access in the Bedrock console
`ValidationException` (thinking + temperature)	Thinking requires `temperature: 1` — this is set automatically, but check you haven't overridden it
`ValidationException` (thinking + max_tokens)	`max_tokens` must be greater than `thinking_budget_tokens` — increase `max_tokens` or reduce the budget
Thinking not appearing	Check the model supports thinking (Claude Sonnet 4+) and `thinking_budget_tokens` is greater than `0`
`ExpiredTokenException`	Your temporary credentials expired — run `aws sso login --profile your-profile`
`The security token included in the request is invalid`	Credentials are invalid or expired — re-authenticate
Credentials not found	Run `aws configure` (static keys) or `aws sso login` (SSO) to set up credentials

Extending This

Ideas for making this more capable:

Add a search_files tool — grep/regex search across the codebase
Add a patch_file tool — edit specific sections instead of rewriting entire files
Add conversation persistence — save/load chat history to disk
Add guardrails — restrict which directories can be written to
Customize streaming display — add progress bars, spinners, or other UI elements
Add error recovery — handle tool failures more gracefully

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
src		src
.gitignore		.gitignore
README.md		README.md
build-sea.sh		build-sea.sh
config.json.example		config.json.example
package-lock.json		package-lock.json
package.json		package.json
sea-config.json		sea-config.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Code Harness

What is this?

Architecture

How the Agent Loop Works

Features

Project Structure

The Tools

Setup

Prerequisites

1. Configure AWS Authentication

Install AWS CLI

Option A — AWS SSO (recommended for organisations)

Option B — Static credentials (personal AWS account)

What your credentials file looks like

2. Enable Model Access in Bedrock

3. Configure the Agent

Available Models on Bedrock

🟣 Anthropic — Claude

🔵 Zhipu AI — GLM

🟢 Alibaba — Qwen

4. Environment Variable Overrides

5. Install & Run

Building a Standalone Binary (SEA)

How It Works — A Walkthrough

1. Loading Config & Creating the Model (src/index.ts)

How thinking works in Strands

2. Defining Tools (src/tools.ts)

3. Creating the Agent

4. The Streaming Loop

Key Concepts for Learners

Troubleshooting

Extending This

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Loading Config & Creating the Model (`src/index.ts`)

2. Defining Tools (`src/tools.ts`)

Packages