Design the Agent-Computer Interface (ACI)

The route

5 steps to Done

1. 01

   Audit your current tool surface

   You cannot design an interface you have not honestly measured.

   Preview prompt + verify gate ▾ Hide ▴

   Audit my agent's current tools against ACI principles. For each tool record: typical output size in tokens, whether output is bounded, whether errors state a cause and suggested next action, whether misuse is guarded (e.g. editing a file never read), and 2-3 transcript examples where the tool confused the model. Score each tool 1-5 on model-friendliness. Research context: SWE-agent found that command simplicity, output windowing, and informative feedback measurably raise task success; raw shells underperform purpose-built commands. Deliver the audit as a table with a fix priority order.

   • ✓ Every tool has output-size data
   • ✓ Confusion cases cite real transcripts
   • ✓ Priority order is justified
2. 02

   Build the windowed file viewer

   The single highest-leverage ACI component in the research.

   Preview prompt + verify gate ▾ Hide ▴

   Replace raw file reads with a windowed viewer. Requirements: open_file(path, line?) shows a window of about 100 lines with line numbers, a header (path, total lines, current window range), and footer hints (lines above/below); scroll_down/scroll_up move the window; goto(line) jumps. Files smaller than the window show fully. The viewer maintains per-file position state across calls. Output is always bounded regardless of file size. Test on a 5,000-line file: the model should be able to navigate to a target function via search + goto without ever receiving the full file.

   • ✓ Window header/footer show position context
   • ✓ Navigation state persists across calls
   • ✓ 5,000-line file never dumps fully
3. 03

   Add validated edits with corrective feedback

   An edit command that cannot fail loudly will fail silently.

   Preview prompt + verify gate ▾ Hide ▴

   Implement ACI-grade editing. Requirements: edit(path, start_line, end_line, replacement) applies only if the file was previously opened (read-before-write guard); after applying, run a syntax/lint check appropriate to the file type; on lint failure, revert the edit and return the error with line numbers and the offending snippet so the model can correct; on success, return the new window around the edit as confirmation. Also implement a string-replace edit variant that fails with a helpful message when the target string is not unique. Test with a deliberately broken edit and verify the revert plus corrective message loop leads the model to a fixed second attempt.

   • ✓ Read-before-write is enforced
   • ✓ Lint failure reverts and explains
   • ✓ Success returns the edited window as evidence
4. 04

   Constrain search and command outputs

   Concise, ranked results are an interface decision, not a nicety.

   Preview prompt + verify gate ▾ Hide ▴

   Redesign search and command execution for bounded, guiding output. Search: find_text(query, path?) returns at most 20 hits as file:line plus a one-line snippet, deduplicated by file, with a 'N more hits truncated' note; find_file(pattern) returns at most 30 paths. Commands: run_command returns combined stdout/stderr truncated to a token budget with head+tail preserved and a marker showing how much was cut, plus the exit code always stated explicitly. Never let any tool response exceed the budget. Verify with a query that matches thousands of lines and a command that prints megabytes.

   • ✓ Hit caps enforced with truncation notes
   • ✓ Exit codes always explicit
   • ✓ Head+tail preserved on big outputs
5. 05

   Benchmark against the raw baseline

   The ACI claim is empirical - test it that way.

   Preview prompt + verify gate ▾ Hide ▴

   Prove the redesign. Take three representative tasks (find and fix a planted bug, add a small feature, answer a codebase question). Run each with (A) the old raw tool surface and (B) the new ACI, same model and system prompt. Compare: turns to completion, total tokens, wrong-file edits, and success. Record results in a small table. Where the ACI did not win, inspect the transcript and identify the interface gap (usually feedback that failed to guide the next action) and fix it. Keep the benchmark script for future harness changes.

   • ✓ Same tasks, model, and prompt across A/B
   • ✓ Turns, tokens, and success recorded
   • ✓ Regressions traced to specific interface gaps

Research-backed

Sources behind this flow