Lesson 1 of 8 · 12 min · Concept content, does not go stale
What a coding agent is (and why it is not a chat)
By the end of this lesson you will be able to:
- Explain the difference between a chat and a coding agent with an example
- Describe the loop: read, plan, act, verify
- Understand why the agent asks permission and what to look at when it does
- Place Claude Code and Codex among the tools that exist
You ask a chat AI: “Make me a page for the bakery, with the opening hours.” It answers with a block of code. You copy it, paste it into an editor, save it under the right name, open it in the browser and see that Saturday's hours are swapped. You explain, it gives you another block, and you start over.
Who did all the work with their hands? You. The chat only wrote text.
Now give the same request to a coding agent, opened in the terminal inside the bakery folder. It sees what is there, tells you its plan, creates the file (depending on the mode, it asks before saving), opens the page to check, and if Saturday is swapped, it fixes it. You decide and confirm. The hands are its.
Chat and agent, side by side
| Chat | Coding agent | |
|---|---|---|
| Where it lives | On a web page or in an app | In the terminal or the editor, inside a folder |
| Sees your files | What you paste or attach | Reads the folder where you opened it |
| Changes files | Not on your computer: it gives you text or a file to download | Yes, depending on the mode and your permissions |
| Checks the result | Some run code, but in their own environment | Runs commands on your computer to verify |
| Who does the work | You | It does, with you supervising |
The “brain” can even be similar. What changes is that the agent has hands and works on your computer.
The loop: read, plan, act, verify
An agent always works in turns of the same loop:
- Read. It opens the files in the folder and looks for what matters.
- Plan. It decides the steps. You can ask it to show you the plan before it does anything (lesson 1/03).
- Act. It creates or changes files and runs commands.
- Verify. It checks whether it worked: it opens the file, runs the program, reads the error message.
If the check fails, it reads the error, adjusts the plan and acts again, until it is done or needs you.
Example
You ask: “On the bakery page, change Saturday's hours to 7:00–13:00.”
Read: it opens index.html and finds the Saturday line.
Plan: “I will change only that line.”
Act: it changes the line; depending on the mode, it first shows you the diff (lesson 0/03) and asks.
Verify: it rereads the file: Saturday says 7:00–13:00 and nothing else changed.
The tools are the hands
An AI model on its own only writes text. The agent is the program around it that turns that text into actions. Each action is called a tool:
- Read files and search for text inside them.
- Edit and create files.
- Run commands in the terminal (the ones from lesson 0/01 and many more).
- In some cases, search the Internet.
When you see “reading index.html” or “running ls” on screen, the agent is using a tool.
Why it asks permission
Reading a file breaks nothing. Deleting, overwriting, installing or sending things over the Internet can break something. So, depending on the mode and the rules, the agent stops before certain actions, shows you what it wants to do and waits for your yes. That is not guaranteed: some modes let it do on its own whatever fits within certain limits (lesson 1/03).
Think of a new helper at the bakery: on day one you do not hand over the key to the safe, you watch how they work. An agent is the same. Some modes ask for fewer permissions, but while you are learning, pick the one that asks the most.
Watch out
The agent makes mistakes, sometimes confidently: “ready and tested” when it is not. It can also be fooled by text it reads, for example a file or a web page with hidden instructions. The permission request is not red tape: it is your moment to look. While you are learning, do not switch it off: not even the experiments folder protects you, because a command can touch other folders. The no-permission mode is only for isolated environments, such as a virtual machine (lesson 1/06).
Tip
When you do not understand what the agent wants to do, refuse and ask. “Explain in plain English what this command does” is a perfectly valid answer to a permission request.
Claude Code and Codex
In this course we use two agents, always side by side:
- Claude Code, from Anthropic (the company behind Claude). It runs in the terminal, and it also exists as an extension for editors and as a desktop app.
- Codex CLI, from OpenAI (the company behind ChatGPT). It runs in the terminal, and it also exists as an extension for editors and inside the ChatGPT desktop app.
Both follow the loop of read, plan, act and verify. Both can ask permission, both have a plan mode, and both read an instructions file in the project folder (CLAUDE.md for one, AGENTS.md for the other, lesson 1/07). Command names and some details differ: you will see them in the next lessons. To find out which plans give access to each one, see the Current state page.
Other coding agents, such as Gemini CLI (Google), Cursor and GitHub Copilot, follow the same idea; a separate page compares them.
Tip
You do not have to choose yet. Almost everything you learn with one applies to the other: the folder for experiments, the plan before acting, reading the diff and the habit of checking.
Exercise
For each task, decide whether a chat is enough or a coding agent would help:
Then, for task 2, write what the agent would do at each step of the loop.
How I know it worked 1 and 3 are for a chat (the result is text for you to read). 2 and 4 are for an agent (there are files on your computer to read and change). For task 2: read the twelve pages, plan the change, change them asking permission, and verify that all of them ended up the same.
If it didn't work
- You hesitated on a task: ask yourself, “Is the result text for me to read, or files on my computer that have to change?” The first is for a chat; the second, for an agent.
- You put task 3 on the agent: that is not wrong, but it is like calling the plumber to change a light bulb. A chat is enough.
- You did not remember the steps of the loop: go back to the bakery example above and copy its structure.
Videos
Código Fonte TV explains what AI agents are in software engineering and how to work with them.
IBM defines agentic coding and shows an iterative workflow in which the agent works on existing code, with confidence and control.
Test what you learned
Corrections to this lesson (1)
- : After an external review: the agent asks for permission «depending on the mode and the rules», with no promise that it always asks; the table now says chat assistants also take files and some run code; the experiments folder is no longer presented as a safety guarantee. Quiz options were reordered.