contenox

What is an AI coding agent? How it works, with an example

Updated

BASICS What is an AI coding agent?

An AI coding agent is a program that uses a language model to do a software task for you, not just suggest code. You give it a task such as “fix the failing login test”. It reads your files, runs commands, edits code, runs the tests again, and keeps going until the task is done or it needs you. Claude Code, Codex, OpenCode, Cursor’s agent and GitHub Copilot’s agents are all coding agents.

The difference from a chatbot is the loop. A chatbot answers once and you copy the code. An agent acts in your project and checks its own work.

What it looks like in practice

You type: “The session test fails since yesterday. Find out why and fix it.”

The agent then works through steps like these, showing each one as it goes:

read_file   src/auth/session.ts
search      "refreshToken" in src/
run         npm test -- session         1 failing
edit_file   src/auth/session.ts         2 lines changed
run         npm test -- session         all passing
answer      "Expiry compared seconds to milliseconds. Fixed in session.ts."

You didn’t open a file. You read a two-line diff and decide whether to keep it.

How does an AI coding agent work?

Every agent, whatever the product, runs the same loop:

  1. You describe the task.
  2. The model gets your task, its instructions and a list of tools it may use.
  3. The model answers with either text or a tool call, such as “read src/auth.ts”.
  4. The agent program runs the tool and sends the result back to the model.
  5. Steps 3 and 4 repeat until the model answers with text instead of a tool call.

The model never touches your disk. It only asks for actions. The agent program on your computer decides whether to carry them out, which is where permission prompts and rules live.

What does the agent actually send to the model?

Tools are just descriptions. The agent program tells the model which tools exist, in a format like this one from Anthropic’s API:

{
  "name": "read_file",
  "description": "Read a file from the project.",
  "input_schema": {
    "type": "object",
    "properties": { "path": { "type": "string" } },
    "required": ["path"]
  }
}

When the model wants to use one, it doesn’t run anything. It answers with a request, and stops:

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "read_file",
  "input": { "path": "src/auth/session.ts" }
}

The agent program reads the file, sends the contents back as a tool_result with the same id, and asks the model again. That’s one turn of the loop. Two things follow from it:

  • Tool descriptions cost tokens on every turn. In the basic loop, every description is sent with every request, so twenty tools with long descriptions are paid for before your task even starts. Some agents, Claude Code among them, now send only the names of MCP tools and load a tool’s full definition when it is needed.
  • The model only ever sees text. Anything a tool returns, a file, a web page, an error, becomes part of what the model reads next. That’s why a malicious line in a README can steer an agent.

OpenAI, Google and others use their own field names, but the shape is the same.

What can a coding agent do?

What its tools allow. Most come with:

  • Read and search files.
  • Edit and create files, usually by replacing specific lines.
  • Run commands: tests, builds, linters, package managers, git.
  • Fetch web pages and documentation.

Many can load more tools through MCP, for example to read GitHub issues, query a database or drive a browser.

Agents do best on bug fixes with a way to reproduce them, adding tests, small features, refactors across many files, and explaining unfamiliar code. They do worst on vague goals with no way to check the result.

Is it the same as Copilot autocomplete or ChatGPT?

No. There are three kinds of AI coding help, and many products now offer more than one:

AutocompleteChatCoding agent
Works onThe next few linesOne questionA whole task
Changes your filesOnly what you acceptNo, you pasteYes
Runs commandsNoNoYes
Checks its workNoNoCan run tests
Your jobTypingAskingReviewing

Autocomplete is still the fastest way to write code you already know how to write. An agent pays off when the task spans several files, needs investigation, or has a clear test.

Where do coding agents run?

  • In a terminal, as a command in your project folder: Claude Code, Codex CLI, OpenCode. See terminal coding agents.
  • In your editor, as a panel next to your code. The Agent Client Protocol (ACP) lets one agent work in several editors.
  • In a desktop app with sessions, diffs and approvals in one window.
  • In your browser, served from your own machine. DeepSeek Harness, DeepSeek’s open-source agent, works this way: npx @deepseek-ai/dsh web starts it on localhost.
  • In the cloud, on a copy of your repository. Codex cloud, Claude Code on the web and GitHub’s Copilot in the cloud work this way: you hand over a task, and get back a branch or a pull request to review.

A local agent works on your real files with your user’s access. A cloud agent works on a copy, which is safer but slower to steer.

Is an AI coding agent safe to use?

It is as safe as what you let it do. An agent that can run shell commands can delete files, push to a remote or print a secret, and a web page or issue comment it reads can contain instructions aimed at it. Three habits cover most of the risk:

Where do agents go wrong?

They fail in familiar ways, and knowing them makes review faster:

  • Plausible but wrong. The code compiles and reads well but solves a slightly different problem.
  • Doing too much. Asked to fix one bug, it refactors three files.
  • Cheating on tests. A test fails, and the agent loosens or skips the test instead of fixing the code.
  • Losing the thread. On long tasks, early instructions get crowded out and the agent drifts.
  • Claiming success. “All tests pass” in the summary is a claim. The diff and your own test run are the evidence.

Clear tasks make the first three less likely, short sessions help with the fourth, and only careful review catches all five.

How do I get started?

You need three things:

  1. An agent: a terminal tool, an editor with an agent panel, or a desktop app.
  2. A model: a hosted model through a subscription or API key, or a local model. See how to choose a model for coding, and AI coding costs for what you will pay.
  3. A project in git, with a clean working tree before each task.

Start with a read-only task: “Explain how sessions are created in this project. Don’t change anything.” Then a small one with a test. Watch what the agent does before you hand it bigger work.

If you want a desktop app that works with the model provider you choose and asks before the actions you gate, Contenox is free and open source.

Related

Esc to close