Coding agent

What you'll build

Step-by-step build

1. 1

   Define the tool surface

   Decide the exact tools the agent gets: read a file, list files, write a file, and run the tests. Keep the set small and each one validated by Zod so the model cannot pass malformed arguments. A tight tool surface is what keeps an agent debuggable.

2. 2

   Implement read and list safely

   Build the read and list tools so they only touch paths inside the target repo, rejecting anything that escapes it. Test them by hand before the model can call them. These give the agent grounding so its plan reflects the real code, not its imagination.

3. 3

   Implement the write tool

   Add a write tool that applies file edits and returns what changed. Constrain it to the repo directory and log every write. This is the most dangerous tool, so treat its output as a diff you will review, never a silent mutation.

4. 4

   Implement the run-tests tool

   Wrap the project's test command so the agent can run it and receive the pass or fail output as text. The test result is the agent's ground truth, the only honest signal that a change works. Verify it by running it manually on a passing and a failing repo state.

5. 5

   Add the planning step

   Before any edits, prompt the model to read the relevant files and produce a short plan of the edits it intends to make. Reviewing the plan separately from the edits catches bad ideas early and cheaply. Print the plan so you can stop a wrong direction before code changes.

6. 6

   Wire the edit-and-test loop

   Let the agent apply its planned edits, run the tests, and read the results. If tests fail, feed the failure output back so it can revise. This feedback loop, edit then test then fix, is the whole point of the project.

7. 7

   Cap iterations and isolate work

   Set a hard limit on retries so a stuck agent gives up instead of thrashing. Run the whole session on a fresh git branch so the main branch is never touched. If the cap is hit without green tests, leave the branch for a human to inspect.

8. 8

   Present the diff and result

   When tests pass, show the full git diff and the final test output for you to accept or reject. Never auto-merge; the human stays the gate. A clear diff plus a green run is what makes the agent trustworthy.

Done when

• ✓Given a small bug and a failing test, it produces edits that make the test pass
• ✓It never writes outside the target repo directory
• ✓When it cannot fix the issue within the cap, it stops and leaves a clean branch
• ✓Every run ends with a reviewable diff and the actual test output
• ✓You can read the log and follow plan, edits, test run, and retries in order

Ship it

This runs as a local CLI rather than a hosted app, since it edits files and runs tests. Publish it as a repo with a README that shows one full example: the task, the plan, the diff, and the passing tests. Note the Groq free-tier limits and warn users to run it only on a repo they can safely branch.

What it proves: Shows you understand the edit-run-test loop at the heart of AI coding tools and can keep a file-editing agent safe and grounded in tests.

Paste this into Cursor, Claude, or ChatGPT and build it step by step.

You are my senior AI engineer pair. Help me build "Coding agent" step by step. An agent here is an LLM that loops over tools; tool-calling means it requests a function like read-file or run-tests and I execute it and return the result. Tests are the ground truth for whether a change is correct.

Stack: Node.js and TypeScript as a CLI, Vercel AI SDK 6 for the tool-calling loop, Groq API for inference, simple-git for branching and diffs, and a sample repo with Vitest or pytest.

Requirements:
1. Give the agent read, list, write, and run-tests tools, each Zod-validated and confined to the repo.
2. Plan the edits before touching files.
3. Loop edit then test then fix, feeding failures back.
4. Cap retries and work on a fresh git branch, never main.
5. End with a reviewable diff and the real test output; never auto-merge.

Work in this order: define tools, then read and list, then write, then run-tests, then planning, then the loop, then the cap and isolation, then the diff view. Give me commands and code for each step and STOP after each so I can test. Do not write the whole app at once.