How the Agent Works

Testy Claw uses a plan-then-execute loop. It reads your task, breaks it into discrete steps, runs each step using the available tools, and stops when the task is complete or a limit is reached.

The agent loop

Each run follows this sequence:

Parse — read the task string and any context files
Plan — ask the model to produce an ordered list of steps
Execute — run each step using the appropriate tool
Observe — feed the tool output back to the model
Repeat — continue until the task is done or maxSteps is reached
Report — print a summary and write the run log to .claw/runs/

Planning

Before executing anything, the agent calls the model with your task and a description of every enabled tool. The model returns a structured plan — an ordered list of tool calls with arguments. You can inspect this plan without running it using testy-claw plan.

terminal

testy-claw plan "scaffold a REST API"

  Plan (5 steps):
  1. shell.exec("mkdir -p src/routes src/middleware")
  2. fs.write("src/index.ts", ...)
  3. fs.write("src/routes/index.ts", ...)
  4. fs.write("src/middleware/auth.ts", ...)
  5. fs.write("package.json", ...)

Execution

Each step calls a tool function with the arguments the model provided. The tool returns a result (file contents, command output, HTTP response, etc.) which is appended to the conversation context. The model uses this to decide the next step.

NoteThe agent never executes arbitrary code directly. Every action goes through a named tool function that you can inspect, restrict, or replace in your config.

Limits and safety

Two config values bound every run:

maxSteps — the agent stops after this many tool calls, even if the task isn't done
timeout — each individual tool call is killed after this many milliseconds

If maxSteps is reached, the agent prints a partial summary and exits with a non-zero code. This makes it safe to use in CI without risk of runaway loops.

Context and memory

Each run starts with a fresh context. The agent has no memory of previous runs unless you explicitly pass a context file with --context. This keeps behaviour predictable and reproducible.

terminal

# Pass extra context to the agent
testy-claw run "refactor the auth module" --context src/auth.ts