What is an AI coding agent? How Claude Code and Codex work
An AI coding agent is an LLM in a loop with tools to read code, edit files and run tests until a task is done. How the loop works, with a runnable Python demo.

An AI coding agent is a language model running in a loop with tools that let it read a codebase, edit files and run commands such as tests, so it can carry a programming task from request to verified change without a human typing each step. Claude Code, OpenAI’s Codex, Cursor’s agent and GitHub Copilot’s agent mode are all built this way. The model decides the next action; the program around it, the harness, executes the action and feeds the result back.
How is a coding agent different from autocomplete or a chatbot?
Autocomplete predicts the next few lines where your cursor is. A chatbot answers in text, and you copy the code across and run it yourself. An agent closes the loop: it runs the code, reads the error, changes the file and runs it again.
Anthropic’s Building effective agents (December 2024) gives the definition I use for any AI agent: systems where LLMs “dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks.” The same post stresses that agents need “ground truth” from the environment at each step. In coding, that ground truth is cheap and honest: the compiler, the test runner and the linter don’t flatter anyone.
How does an AI coding agent work?
Claude Code’s documentation, How Claude Code works, describes the loop in three phases: gather context, take action, verify results. They blend together, and the model chooses each step based on what the previous one returned. Its own example for “fix the failing tests” is a good trace of the whole idea:
- Run the test suite to see what’s failing.
- Read the error output.
- Search for the relevant source files.
- Read those files.
- Edit the files to fix the issue.
- Run the tests again to verify.
The docs sort Claude Code’s built-in tools into five groups: file operations, search, execution (shell commands, tests, git), web, and code intelligence. Then they say the line that matters for anyone building one: “Claude Code is the layer around the model that provides the tools and manages the context the model sees.” That layer is the agent harness, and most of the difference between two coding agents on the same model lives there.
Each tool is offered to the model through tool calling: the model emits a structured request such as “run pytest tests/test_auth.py”, the harness runs it and returns the output as the next message.
What does the loop look like in code?
Here is the loop with the model replaced by a scripted policy, so it runs without an API key. The repository, the bug and the tests are real; policy() makes the choices a model would make from the same observations.
# agent_loop.py: the loop inside a coding agent, with a scripted stand-in for the model.
# Python 3 standard library only. No API key: policy() plays the model's part.
import pathlib, subprocess, sys, tempfile
repo = pathlib.Path(tempfile.mkdtemp())
(repo / "prices.py").write_text(
"def total(items, tax=0.18):\n"
" return round(sum(items) * tax, 2)\n")
(repo / "test_prices.py").write_text(
"from prices import total\n"
"assert total([100, 50]) == 177.0, total([100, 50])\n"
"print('tests passed')\n")
# The tools the harness exposes. The model only ever asks for these by name.
def run_tests():
p = subprocess.run([sys.executable, "test_prices.py"], cwd=repo,
capture_output=True, text=True)
return (p.stdout + p.stderr).strip().splitlines()[-1]
def read_file(path):
return (repo / path).read_text()
def edit_file(path, old, new):
f = repo / path
f.write_text(f.read_text().replace(old, new, 1))
return f"edited {path}"
TOOLS = {"run_tests": run_tests, "read_file": read_file, "edit_file": edit_file}
def policy(history):
"""Stand-in for the LLM: picks the next tool call from what it has seen."""
last = history[-1][1] if history else ""
if not history:
return ("run_tests", {})
if "AssertionError" in last:
return ("read_file", {"path": "prices.py"})
if "sum(items) * tax" in last:
return ("edit_file", {"path": "prices.py",
"old": "sum(items) * tax", "new": "sum(items) * (1 + tax)"})
if last.startswith("edited"):
return ("run_tests", {})
return ("done", {})
history = []
for step in range(1, 8): # the harness owns the budget, not the model
name, args = policy(history)
if name == "done":
print(f"step {step}: done")
break
result = TOOLS[name](**args)
history.append((name, result))
print(f"step {step}: {name}({args.get('path', '')}) -> {result.splitlines()[-1][:48]}")
Output (Python 3.13.11):
step 1: run_tests() -> AssertionError: 27.0
step 2: read_file(prices.py) -> return round(sum(items) * tax, 2)
step 3: edit_file(prices.py) -> edited prices.py
step 4: run_tests() -> tests passed
step 5: done
Swap policy() for a call to a model API with the three tools described as JSON schemas and you have the skeleton of a real coding agent. I build that version step by step in how to build an AI agent. Notice what the harness controls even in this toy: which tools exist, where they can write (one temp directory), and how many steps the model gets.
Why does the harness matter as much as the model?
Two research results from 2024 make the case.
The SWE-agent paper (May 2024) argued that language model agents are “a new category of end users” that need interfaces built for them, which the authors called an agent-computer interface. Their custom commands for editing files, navigating the repository and running tests took the agent to 12.5% on SWE-bench, well above what non-interactive approaches had reached at the time. Better tools, better results.
Agentless (July 2024) went the other way: a fixed three-phase pipeline of localization, repair and patch validation, with no model-directed loop at all. It scored 32% on SWE-bench Lite at a reported cost of $0.70, beating the open-source agents of the time. The lesson I take from the pair is the workflows vs agents trade-off: when the task shape is known, a fixed pipeline can beat a free-roaming loop.
Anthropic found the same thing building its own SWE-bench agent, writing that they “spent more time optimizing our tools than the overall prompt.” One fix was making a file tool require absolute paths after the model kept getting relative paths wrong.
How good are coding agents now?
Benchmarks moved fast. The original SWE-bench paper (October 2023) reported Claude 2 resolving 1.96% of real GitHub issues. By early 2026, OpenAI wrote that state of the art on SWE-bench Verified had gone from 74.9% to 80.9% in six months, and stopped reporting it because of flawed tests and training contamination. I go through that story in what SWE-bench is.
METR measures progress differently, as the length of task (in human time) an agent can finish half the time. In their March 2025 paper, Claude 3.7 Sonnet’s 50% time horizon was about 50 minutes, and the frontier horizon had been doubling roughly every seven months since 2019.
Benchmarks aren’t your codebase, though. The same group’s randomized trial found experienced developers using early-2025 tools on their own mature projects took 19% longer with AI allowed, while believing they’d been faster.
Where do coding agents break?
Context. An agent knows only what it reads. Large repositories, unwritten conventions and tribal knowledge are where it guesses. Instruction files such as AGENTS.md or CLAUDE.md exist to close that gap.
Verification. An agent is only as good as the checks it can run. With no tests, “verify results” means re-reading its own code, which catches much less.
Security. An agent runs commands with your permissions and reads untrusted text: issues, web pages, dependency READMEs. That’s the setup for prompt injection, which is why the serious agents ship with sandboxes. I cover how those work in sandboxing AI agents.
Cost. Every turn resends the growing transcript, so long sessions get expensive. Effort settings and prompt caching help; I priced one model’s version in an earlier post on Claude Opus 4.5’s effort parameter.
What I would do
- Give the agent a fast, trustworthy test command. That one thing improves results more than any prompt tweak, because it’s the ground truth the loop runs on.
- Write a short instruction file. Build, test and lint commands, the layout of the repo, and the two or three conventions people get wrong.
- Start in a sandbox, with network off. Widen permissions when a task needs them, not by default.
- Keep tasks reviewable. One issue per session and a diff a human can read in ten minutes. For larger work, write the intent down first, as in spec-driven development.
- Run several attempts in parallel when it’s cheap. Separate git worktrees let you compare approaches without collisions.
- Measure on your own tasks. Keep twenty real issues from your backlog with known fixes and rerun them when you change model or harness.
FAQ
What is the best AI coding agent?
It depends on your stack, your codebase and which harness you prefer, and the ranking changes every few months. Test two or three on a set of your own past issues with known fixes, and compare resolved tasks, review effort and cost.
Is an AI coding agent the same as an AI code assistant?
Not quite. An assistant suggests code; an agent also runs commands, reads the results and iterates. Most assistants now have an agent mode, so the difference is in how you use the tool more than which product you bought.
Can AI coding agents work without supervision?
On well-specified tasks with good tests, they can run unattended for a while, especially in a sandbox. A human should still review the change before it merges, because passing tests don’t prove the change does what you wanted.
What is an agentic coding tool?
The same thing: a coding tool where the model takes actions (editing files, running commands) in a loop, rather than only producing text. Anthropic’s docs describe Claude Code as “an agentic coding tool.”
Sources
- Anthropic, Building effective agents, December 19, 2024
- Anthropic, How Claude Code works and Claude Code overview (read 2026-10-31)
- Yang et al., SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering, May 2024
- Xia et al., Agentless: Demystifying LLM-based Software Engineering Agents, July 2024
- Jimenez et al., SWE-bench: Can Language Models Resolve Real-World GitHub Issues?, October 2023
- OpenAI, Why we no longer evaluate SWE-bench Verified, February 23, 2026
- METR, Measuring AI Ability to Complete Long Software Tasks, March 2025
- METR, Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity, July 2025