How an agent reads and edits your repo

Before an agent can act, it needs context it wasn't handed directly. It does this by searching your repository: grepping for relevant symbols, listing directory structures, reading files it suspects are related to the task, and following imports or references to build up a working picture. This is why you don't need to paste every relevant file into the chat the way you would with a plain chatbot — the agent goes looking for what it needs, the same way you would open files while investigating a bug.

Good agents are efficient readers: they search narrowly first, widen only if needed, and avoid loading your entire codebase into context just because they can. A well-scoped task (see the next page) makes this search easier and more accurate.

Once it has enough context, the agent forms a plan — usually a short, explicit sequence of steps: "1. Add a route handler. 2. Register it in the router. 3. Write a test. 4. Run the test suite." Some tools show you this plan before acting; others fold planning and acting together and show you the plan retroactively through the sequence of edits. Either way, a plan exists, even if implicit — the agent isn't guessing edit-by-edit with no sense of the destination.

This is the step that makes agents categorically different from chat: they can actually do things, not just describe them. Acting usually means two kinds of operations:

• File edits — creating, modifying, or deleting files, typically shown to you as a diff (what changed, line by line)
• Command execution — running things in a terminal: installing a dependency, running a test suite, starting a dev server, invoking a linter or formatter

Both of these are real side effects on your machine or repository, which is exactly why review checkpoints matter (covered in depth on the guardrails page). An agent that can run rm -rf or git push --force is not fundamentally different, mechanically, from one running pytest — the tool doesn't inherently know which commands are routine and which are dangerous unless you or its configuration tells it.

The step that closes the loop and separates agents from one-shot code generation: after acting, the agent reads the result. If it ran a test suite, it reads the pass/fail output. If it ran a linter, it reads the warnings. If a command errored, it reads the stack trace. This feedback becomes new context for another round of planning — "the test failed because of a missing import, let me fix that" — without you needing to copy-paste the error back in yourself.

This read-act-check cycle can repeat many times within a single task. A well-behaved agent will eventually converge (tests pass, the goal is met) or recognize it's stuck and stop to ask for help, rather than looping indefinitely on a problem it can't solve.

Finally, the agent reports back — usually as a summary of what changed, plus the diffs themselves for you to review. This is the point where your judgment re-enters the loop fully: accept, request changes, or reject and try a different instruction.

Knowing this loop exists changes what you do when something goes wrong. If an agent's plan looks off before it acts, you can redirect early instead of waiting for a bad diff. If it's stuck retrying the same failing fix, you can supply the one piece of context it's missing (a hint about why the test exists) rather than re-explaining the whole task. And if it reports success, you know that claim is based on a command actually running and reporting output — not the model's confidence alone, which is worth remembering but doesn't replace reading the diff yourself.