How does a coding agent work?

A repository-shaped agent loop

A coding agent is not a special neural-network architecture. It is an AI agent connected to an interface for software work: repository search, file reads and patches, terminals, version control, test runners, browser tools, and sometimes issue trackers or deployment systems.

flowchart LR
  G[Task + repository policy] --> C[Construct current context]
  C --> M[Model emits text or tool request]
  M --> P{Schema, path, policy, approval}
  P -->|allow| X[Read, search, edit, or execute]
  P -->|deny| O[Denial]
  X --> O[Output, error, or effect]
  O --> C
  M --> V[Completion claim]
  V --> Q[Diff + acceptance evidence]

The model selects among the actions described in its context. The harness owns what those actions actually do, where they run, how long they may run, what output returns, and whether the loop may continue.

Before the first model call

A useful coding prompt is assembled, not merely typed. A harness may combine:

• model-specific system instructions and tool schemas;
• repository and directory instructions such as AGENTS.md;
• the exact working directory, shell, sandbox, network, and approval mode;
• the user's task and attached artifacts;
• selected file, symbol, issue, or editor context;
• conversation history, durable task state, and remaining budgets.

This is why the same model can behave differently in a chat page, IDE, terminal agent, or CI worker. The interface determines what the model can observe and propose. The runtime determines which proposals can become effects.

The inner loop, step by step

A typical implementation repeatedly performs five operations:

1. send the current messages, instructions, and tool definitions to the model;
2. receive typed content such as text, a tool request, or a stop reason;
3. validate and execute each allowed tool request;
4. append matching tool results—including useful failures—to the conversation state;
5. call the model again until it stops requesting tools or a runtime limit interrupts the turn.

Useful tool failures stay inside the loop as observations. “File not found,” a non-zero test exit, or a denied command can let the model choose another path. Infrastructure failures, cancellation, and uncertain external effects need different recovery rules and cannot be flattened into friendly text.

The tool surface changes capability

One unrestricted shell tool is expressive but difficult to inspect and gate. Dedicated read_file, apply_patch, search, test, and browser tools create narrower seams for path validation, approvals, logging, staleness checks, output limits, and user-facing progress.

Tool descriptions and schemas are part of the model's action interface. They help the model select and format a request; they do not grant permission. A path that is valid JSON may still escape the workspace. A command that parses may still need approval. MCP can add tools from another process, but the host remains responsible for authority and consent.

Context is working memory, not the repository

The model does not continuously see every file. The harness selects repository instructions and observations into a finite context window. Search and file reads reveal more state only when requested or proactively supplied.

As a run grows, command output, diffs, and repeated file contents compete for that space. Harnesses may truncate output, preserve stable prompt prefixes, compact old events into summaries, or move large artifacts outside the conversation. Compaction is lossy derived state; canonical files, approvals, and test results remain in their authoritative systems.

“Done” has two meanings

Many simple agent loops stop when the model returns text instead of another tool request. That is a protocol stop, not proof that the engineering task succeeded.

A useful workflow adds a task completion gate: inspect the diff, confirm the requested files and behaviour, run proportionate checks, preserve pre-existing changes, and surface unresolved uncertainty. The model's final message is a claim about work; the repository and verification evidence show what actually happened.

Git worktrees or other disposable environments make concurrent and experimental work safer. Exact working directories, secret filtering, network policy, command timeouts, cleanup, and approval identity belong to the runtime, not to a prompt asking the model to be careful.

What current implementations teach

Three complementary readings expose different layers:

• Codex: Unrolling the Codex agent loop documents how one production harness builds prompts, carries tool calls and outputs across requests, manages a growing context, and ends a user turn. Codex as a platform places that loop inside a reusable harness with state, streaming, sandboxing, approvals, and application integration.
• Minimal harness: Build Your Own Coding Agent exposes the compact provider request → tool dispatch → tool result → repeat skeleton before adding permissions, compaction, subagents, and MCP.
• Claude Code: Claude Code Unpacked maps a much broader tool and command surface from publicly available source. It is valuable for architectural questions, but it is unofficial, tied to a dated snapshot, and includes hidden or experimental paths that should not be treated as stable product contracts.

The stable lesson is not the number or name of tools in one product. It is that coding-agent capability emerges from the model and its agent–computer interface together.

Evidence for a coding-agent run

Judge a run using the frozen task and repository state, not the confidence of its narration. Preserve the final diff, file effects, commands and exit statuses, environment versions, permissions, retries, latency, token use, and terminal reason.

Representative trials should include misleading test names, stale instructions, failing setup, large outputs, missing tools, denied commands, concurrent edits, and pre-existing user changes. Separate model quality from harness correctness: deterministic tests can verify path resolution, patch application, output truncation, timeout cleanup, approval identity, and terminal rules without calling a model.