ai / agents
An agent is a software program that runs tools in a loop to achieve a goal. I state the goal.
The loop
One pass through the loop is a turn. In a turn, the model reads the context and then replies or calls a tool. A tool call runs outside the model: a web search, a shell command, a file edit, or a screenshot. The result goes into the context, and the next turn starts. The loop stops when the model replies without a tool call, or when the harness stops it.
user: check test status
model calls tool: go test ./...
tool result: ok github.com/croaky/blog 0.5s
model replies: All tests pass.The parts
Each layer is a separate decision. I change them at different rates.
- Model. The weights and the tier. I change this most often.
- Router. The policy that picks a model per task and fails over when a provider is down. See ai / router.
- Harness. The program that runs the loop. It owns the UI, the tools, and the permission prompts. See ai / harness.
- Context. What the agent reads before it acts: rules files, the repo, and the plan. See ai / context.
- Tools. What a turn can do. The harness supplies file edits and
the shell. Every other tool is a CLI program on
$PATH, such as browse for screenshots and sockeye for changes and checks. I do not use MCP here. A CLI has a--help, a man page, and an exit code, and the agent already knows the shell. - Verification. How I trust the result without reading every line. See git / workflow.
The same layers exist when my application calls a model. See ai / api. The MCP server I run is on that side: it gives a chat client tools, not my terminal.
Parallel agents
I run several agents at once in separate harness tabs, each in its own git worktree. Each worktree gets its own port and database, so the agents do not collide.
# tab 1
cd ~/.worktrees/app/APP-1A && PORT=3001 go run .
# tab 2
cd ~/.worktrees/app/APP-2B && PORT=3002 go run .