AI coding agent harness like Claude Code

A developer gives a coding task. An AI model reads files, runs commands, edits code and runs tests in a loop until it's done. Make it safe and reliable.

1. Requirements

Functional

• Take a coding task in plain words.
• Read, search and edit files; run commands and tests.
• Show each step; ask before risky actions.
• Undo changes.

Non functional

• Never runs a denied command, whatever the model says.
• Stops on step, time and cost limits.
• Fits work into the model's context window.
• Recovers from tool errors instead of crashing.

Questions to ask

• Runs on the developer's machine or in the cloud?
• Which tools: read, write, search, shell, browser?
• What needs human approval?
• Limits on time, steps and cost?

2. Estimates

3. API

model -> harness: { tool: "read", args: { path } }   or   { done: true, text }
harness -> model: tool result text (trimmed if long)
tools: read(path), write(path, text), edit(path, search, replace), search(pattern), shell(cmd)

4. Data model

session log: every message and tool call, in order (for resume and review)
checkpoints: file snapshots before each edit, for undo
permissions: allow list per tool and command pattern
project notes: a file like AGENTS.md loaded at start

5. High level design

Follow one request at a time, top to bottom.

One loop step

1. Developergives the task
2. Harnesssends task, tool list and project notes to the model
3. Modelreplies with a tool call, or done
4. Permission checkallow list, approval prompt, or deny
5. Tool runnerruns with a timeout in a sandbox, trims long output
6. Harnessadds the result to the log and loops

Finish

1. Modelsays done
2. Harnessruns the tests
3. Checkpointsfile snapshots for undo
4. Developerreviews the diff

6. Deep dives

What does the loop look like?

Send the task and tool list to the model. If it asks for a tool, the harness runs it and sends back the result. Repeat until the model says done or a step limit hits.

How do you keep it safe?

The harness enforces permissions, not the model: reads are free, writes and shell need approval or an allow list, dangerous commands are denied. Run in a sandbox or container when unattended.

What about the context window filling up?

Trim long tool outputs, read files in parts, and when the conversation gets big, summarise older steps and keep the newest in full.

How does it recover from mistakes?

Tool errors go back to the model as text so it can try another way. Checkpoints before each edit allow undo. Tests are the judge of done, not the model's word.

See the core idea run

Core logic (JavaScript, tested)

Copy// An AI coding agent is a loop: the model asks for a tool, the harness runs it and sends back the result,
// until the model says it is done. The harness, not the model, enforces limits and permissions.
async function agentLoop(model, tools, task, { maxSteps = 8, allow = () => true } = {}) {
  const log = [{ role: "user", text: task }];
  for (let step = 1; step <= maxSteps; step++) {
    const reply = await model(log);
    if (reply.done) return { ok: true, answer: reply.text, steps: step, log };
    const { tool, args } = reply;
    let result;
    if (!tools[tool]) result = `error: no tool ${tool}`;
    else if (!allow(tool, args)) result = `denied: ${tool} needs approval`;
    else {
      try {
        result = await tools[tool](args);
      } catch (e) {
        result = `error: ${e.message}`; // errors go back to the model, they don't crash the loop
      }
    }
    log.push({ role: "tool", tool, text: String(result) });
  }
  return { ok: false, answer: "stopped: step limit", steps: maxSteps, log };
}

7. Failures

8. Trade-offs

• More autonomy is faster but riskier; approval per action is safe but slow. Allow lists sit in between.
• Giving the model all files is simple but blows the context; search and read on demand scales.

Wrap up