# How coding agents work

A coding agent is a model in a loop, wrapped by a harness that runs tools; this page maps that loop and where the other concepts plug in.

> A coding agent is a language model in a loop: it decides the next step, and the harness runs the tool and feeds the result back. The loop repeats until the task is done.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work

**Diagram:** The model only decides; the harness acts, and every result returns to the context the model reads next.

- Context window — instructions, history, results
- Model decides — probabilistic
- Harness runs tool — deterministic, checks permissions
- Result — files, shell, network output
- Centre: agent loop

A coding agent is two things working together. The **model** reads text and predicts what to do next. The **harness** is the ordinary program around it: it builds the model's input, runs the tools the model asks for, and decides when the loop ends.

The model never touches your files. It emits a request such as "run `pnpm test`", and the harness decides whether to run it, runs it, and puts the output back in front of the model. Everything the model knows at any moment is whatever fits in its **context window**.

## Why it exists

Without this split, you would paste code into a chat, copy answers back and run commands yourself. The loop automates that hand-off. But it also explains the typical failures: the model guesses a command because nothing in its context says otherwise, or it "forgets" a rule because a long session pushed the rule out of focus. You cannot fix those failures if you think of the agent as a single opaque thing.

## How it works

**Diagram:** The harness builds the context and runs the tools; the model only chooses between an answer and a tool call, and long sessions get summarized or trimmed to fit the window.

- Harness assembles — prompt, guidance, task, history
- → context
- Model responds — final answer or tool call
- → tool call
- Harness checks — permissions, or asks you first
- → allowed
- Tool runs — result joins the context

<note>

Rule of thumb for the whole module: anything you need to be *guaranteed* belongs in the harness. Anything you can only *ask for* lives in the context and can be missed.

</note>

## What the next concepts add

- [Instruction files](https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files) — guidance loaded into the context on every run.
- [Skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills) — know-how loaded into the context only when relevant.
- [MCP](https://ai-sw-factory.mellicci.dev/fundamentals/mcp) — tools the harness gets from external servers.
- [Hooks](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) — harness code that runs at fixed points in the loop.
- [Subagents](https://ai-sw-factory.mellicci.dev/fundamentals/subagents) — separate loops with their own context, called from the main one.
- [Plugins](https://ai-sw-factory.mellicci.dev/fundamentals/plugins) — a bundle that installs the pieces above together.
- [Headless execution](https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution) — running the loop with nobody at the keyboard.
- [Loops](https://ai-sw-factory.mellicci.dev/fundamentals/loops) — keep an agent working toward a goal until a stop condition holds.
- [Sandboxing & devcontainers](https://ai-sw-factory.mellicci.dev/fundamentals/sandboxing) — where the agent runs and what it can reach if something goes wrong.
- [Security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) — what the harness lets the loop touch.
- [Your first feedback loop](https://ai-sw-factory.mellicci.dev/fundamentals/your-first-feedback-loop) — combining all of it into a small factory.

## Key terms

- **Model** — the language model that decides the next step; probabilistic.
- **Harness** — the program that runs tools and controls the loop; deterministic.
- **Agent loop** — model decision, tool execution, result feedback, repeated.
- **Context window** — the finite text the model can read at once.
- **Tool** — a capability the harness exposes, such as file edit or shell.