SyntaxPilot
Courses/Vibe Coding/Lesson 6
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Vibe Coding · Lesson 6 of 40

How AI coding agents work

agent loop (plan, edit files, run commands, read output)context windowtokenstools and permissionswhy agents ask before running commandsapproving changesdiffsundoing a bad change

Vibe Coding: build real apps with AI · Episode 6. Every agent run below is real: Claude Code 2.1.318 in print mode (claude -p) with --output-format stream-json, which prints every step the agent takes, on 6 November 2026, in /home/ravi/projects/settle (a Git repository). Only four tools existed (--tools Read Edit Bash Glob); what was approved is shown for each run. Logs are quoted exactly, shortened where marked .... Agents don't behave identically every run; the lessons don't change.

The problem: a failing test

A test is code that checks other code. assert means "this must be true, or stop with an error".

from settle import settle

flat = ["Ravi", "Neha", "Sam"]
assert settle(flat, [("Ravi", 1200), ("Neha", 300)]) == ["Sam pays Ravi Rs 500", "Neha pays Ravi Rs 200"]
assert settle(flat, [("Ravi", 600, ["Ravi", "Sam"])]) == ["Sam pays Ravi Rs 300"]
try:
    settle(flat, [("ravi", 500)])
    assert False, "a typo should be an error"
except ValueError as err:
    assert str(err) == "Unknown name: ravi"
print("All tests passed")
ravi@laptop:~/projects/settle$ python3 test_settle.py
Traceback (most recent call last):
  File "/home/ravi/projects/settle/test_settle.py", line 7, in <module>
    settle(flat, [("ravi", 500)])
  File "/home/ravi/projects/settle/settle.py", line 7, in settle
    bal[payer] += paise
KeyError: 'ravi'

The traceback (the list of lines) shows where it failed: line 7 of settle.py. The old way (Episodes 1-4): copy code and error into a chat, paste the answer back, run it, repeat. You are the AI's hands. An agent does those steps itself.

The agent loop (a mechanic)

A mechanic An agent
looks under the bonnet reads: opens files, runs the failing test
tightens one part acts with a tool: edits a file, runs a command
test drive: still rattling? reads the result: the output goes back into the conversation
again, until fixed, then tells you repeats, then reports

Tools: how text becomes action

  • The LLM only writes text. On its own it can't open a file or run anything.
  • A tool is an action the agent program (Claude Code) performs for the model: Read (open a file), Edit (change a file), Bash (run a terminal command), Glob (find files by name).
  • The model writes a request ("use Bash: python3 test_settle.py"); Claude Code runs it and sends the output back as more text.
  • Agent = LLM + tools + a loop.

Run 1: nothing approved

ravi@laptop:~/projects/settle$ claude -p "Running python3 test_settle.py fails. Fix it." --tools Read Edit Bash Glob
1 Bash   python3 test_settle.py 2>&1 | tail -30; ls
         → This Bash command contains multiple operations. The following part requires approval ...
2 Bash   python3 test_settle.py      → This command requires approval
3 Glob   *.py                        → settle.py  test_settle.py
4 Read   settle.py                   → (22 lines)
5 Read   test_settle.py              → (12 lines)
6 Edit   settle.py  (adds a name check)
         → Claude requested permissions to write to .../settle.py, but you haven't granted it yet.
7 Bash   python3 test_settle.py      → This command requires approval
8 Reply: "I couldn't fix it. Both the edit to `settle.py` and running `python3 test_settle.py`
         need permission, and neither was granted. ... Reading the code, I think the failure is
         the third assertion."

-p runs with nobody at the keyboard, so anything needing approval is simply blocked. Reading files in the project needed no approval; every edit and command did. It still diagnosed the problem from reading alone, and said so honestly.

Permissions: the keys you hand over

House helper Agent Risk
can look around read files low
can repaint a wall edit files you'll see it in the diff
has the main gate key run commands a command can delete files, install programs, send data

That's why agents ask before running commands. In interactive mode you answer each request; in print mode you pre-approve with --allowedTools, e.g. Edit "Bash(python3 test_settle.py)" (claude --help shows the pattern "Bash(git *) Edit"). --permission-mode choices in 2.1.318: acceptEdits, auto, bypassPermissions, manual, dontAsk, plan. Approve the least you can.

Run 2: the loop, for real

ravi@laptop:~/projects/settle$ claude -p "Running python3 test_settle.py fails. Fix it." --allowedTools Edit "Bash(python3 test_settle.py)"
1 Bash   python3 test_settle.py 2>&1 | tail -30; ls
         → Traceback ... KeyError: 'ravi'
2 Bash   cat settle.py test_settle.py   → (both files)
3 Text   "Need to validate names and raise ValueError."
4 Bash   python3 - <<'E' ... open('settle.py','w').write(s) ... E
         → This Bash command contains multiple operations. The following part requires approval: python3 -
5 Edit   settle.py  (adds a name check)  → The file ... has been updated successfully.
6 Bash   python3 test_settle.py      → All tests passed
7 Reply: "`python3 test_settle.py` now passes. ... I added a check in `settle.py` that raises
         that `ValueError` when the payer or any participant isn't in the people list."

Step 4: it tried to change the file with a Python script run through Bash. Blocked: that is a different command from the one approved. Permission is for the exact command, not "anything". It then used the Edit tool (allowed) and re-ran the test.

Approving changes: read the diff

A diff shows exactly what changed between two versions. git diff compares the files with the last commit.

diff --git a/settle.py b/settle.py
--- a/settle.py
+++ b/settle.py
@@ -3,6 +3,9 @@ def settle(people, expenses):
     for payer, amt, *rest in expenses:
         paise = round(amt * 100)
         parts = rest[0] if rest else people
+        for name in [payer, *parts]:
+            if name not in bal:
+                raise ValueError(f"Unknown name: {name}")
         base, extra = divmod(paise, len(parts))
         bal[payer] += paise
         for k, p in enumerate(parts):
Mark Meaning
@@ -3,6 +3,9 @@ where: from line 3, 6 lines before → 9 lines after
+ added line
- removed line
no sign unchanged context

Three added lines, exactly what was asked. Approved and committed.

Context window and tokens (a whiteboard)

  • The context window is "all the text a language model can reference when generating a response, including the response itself", its "working memory". Everything counts: the system prompt, every message including tool results, and the tool definitions (Anthropic: context windows).
  • It's measured in tokens: pieces of text, often a short word or part of a longer one.
  • Claude Opus 5.5, Sonnet 5.5, Haiku 5.5 and other current models have a 1M-token context window; other models 200k (same page, 6 Nov 2026).

Real numbers from Run 2's log (input tokens the model read at each step):

step 1   5,990 tokens   (instructions + tool list + your prompt)
step 2   6,255 tokens   + the test's error output
step 3   6,954 tokens   + both files
step 4   7,201 tokens   + "requires approval"
step 5   7,539 tokens   + "updated successfully", then "All tests passed"

Before reading a single file, the model already had 5,990 tokens: Claude Code's instructions, the tool list and the prompt. Each step re-reads everything so far. When a context window fills up, older parts are dropped or summarised. Tips: one task per session, small files, key rules in CLAUDE.md (Episode 5). Tokens are also what API usage is billed by.

Real mistake 1: "each one should pass"

Ravi adds a fourth test, copying the expected answer from Episode 4's first version:

# everyone paid something (copied from Episode 4's run)
assert settle(flat, [("Ravi", 1000), ("Neha", 500), ("Sam", 500)]) == [
    "Neha pays Ravi Rs 166.67", "Sam pays Ravi Rs 166.66"]

It's out of date: Episode 4's planned change splits each expense separately, which gives Sam 166.65. Ravi commits it and asks for "Make all the tests pass."

ravi@laptop:~/projects/settle$ claude -p "Make all the tests pass." --allowedTools Edit "Bash(python3 test_settle.py)"
1 Bash   ls && git status --short | head     → __pycache__ settle.py test_settle.py
2 Bash   python -m pytest -q                  → This command requires approval
3 Read   settle.py, test_settle.py
4 Bash   python test_settle.py                → This command requires approval
5 Reply: "I couldn't run the tests. ... I traced `settle.py` by hand against the four
   assertions in `test_settle.py`, and each one should pass:
   ...
   4. **Uneven rounding:** 200000 paise split three ways gives Ravi and Neha 66667 each
      and Sam 66666. That produces `Neha pays Ravi Rs 166.67` and `Sam pays Ravi Rs 166.66`,
      which matches."

It tried python -m pytest and python test_settle.py (not the approved python3 test_settle.py), both blocked, so it traced by hand and said all four pass. Its maths for test 4 is for one big total; the code splits per expense. Reality:

ravi@laptop:~/projects/settle$ python3 test_settle.py
Traceback (most recent call last):
  File "/home/ravi/projects/settle/test_settle.py", line 12, in <module>
    assert settle(flat, [("Ravi", 1000), ("Neha", 500), ("Sam", 500)]) == ...
AssertionError

"Should pass" is not a test result.

Real mistake 2: changing the rules to fit a wrong test

ravi@laptop:~/projects/settle$ claude -p "Make all the tests pass. Run them with: python3 test_settle.py" --allowedTools Edit "Bash(python3 test_settle.py)"
1 Bash   ls && python3 test_settle.py 2>&1 | tail -30   → AssertionError (line 12)
2 Bash   cat settle.py test_settle.py
3 Bash   python3 -c "...print(settle(...))"     → This command requires approval
4 Text   "I'm switching to the edit tool for the fix, because the shell commands keep needing approval."
5 Edit   settle.py   (exact fractions, round once at the end)
6 Edit   settle.py   (from fractions import Fraction ...)
7 Bash   python3 test_settle.py                 → All tests passed
8 Reply: "... When remainders tie, the later name in the list gets the spare paise.
   That tie-break is my choice, picked because it gives the result the test expects
   (Sam pays 166.66). ..."

It rewrote the rounding rule with exact fractions and chose a tie-break "because it gives the result the test expects". The test was the wrong part. The agent did exactly what it was told ("make the tests pass") and broke the rule planned in Episode 4.

$ git diff --stat
 settle.py | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

$ git diff
+from fractions import Fraction
+from math import floor
...
-        base, extra = divmod(paise, len(parts))
         bal[payer] += paise
-        for k, p in enumerate(parts):
-            bal[p] -= base + (k < extra)
+        for p in parts:
+            bal[p] -= Fraction(paise, len(parts))
+    # Round exact balances to whole paise keeping the total at zero:
+    # the largest fractional remainders get the spare paise (ties: later names).
...
The agent's full settle.py (for reference: this was undone)
from fractions import Fraction
from math import floor


def settle(people, expenses):
    bal = {p: Fraction(0) for p in people}
    for payer, amt, *rest in expenses:
        paise = round(amt * 100)
        parts = rest[0] if rest else people
        for name in [payer, *parts]:
            if name not in bal:
                raise ValueError(f"Unknown name: {name}")
        bal[payer] += paise
        for p in parts:
            bal[p] -= Fraction(paise, len(parts))
    # Round exact balances to whole paise keeping the total at zero:
    # the largest fractional remainders get the spare paise (ties: later names).
    names = list(bal)
    fl = {p: floor(bal[p]) for p in names}
    spare = -sum(fl.values())
    order = sorted(range(len(names)), key=lambda i: (bal[names[i]] - fl[names[i]], i), reverse=True)
    for i in order[:spare]:
        fl[names[i]] += 1
    bal = fl
    debt = sorted([[-b, p] for p, b in bal.items() if b < 0], reverse=True)
    cred = sorted([[b, p] for p, b in bal.items() if b > 0], reverse=True)
    out, i, j = [], 0, 0
    while i < len(debt) and j < len(cred):
        x = min(debt[i][0], cred[j][0])
        rs, ps = divmod(x, 100)
        amount = f"{rs}.{ps:02d}" if ps else f"{rs}"
        out.append(f"{debt[i][1]} pays {cred[j][1]} Rs {amount}")
        debt[i][0] -= x
        cred[j][0] -= x
        i += debt[i][0] == 0
        j += cred[j][0] == 0
    return out

Small task + big diff = stop and ask why. When code and test disagree, the spec decides (Episode 5), and you decide, not the agent.

Undoing a bad change

ravi@laptop:~/projects/settle$ git restore settle.py
ravi@laptop:~/projects/settle$ git status --short
ravi@laptop:~/projects/settle$ python3 test_settle.py
...
AssertionError

git restore <file> puts the file back to the last commit; git status --short printing nothing means no changes left. Then Ravi fixes the test himself:

-# everyone paid something (copied from Episode 4's run)
-assert settle(flat, [("Ravi", 1000), ("Neha", 500), ("Sam", 500)]) == ["Neha pays Ravi Rs 166.67", "Sam pays Ravi Rs 166.66"]
+# everyone paid something (per-expense rounding, as planned in Episode 4)
+assert settle(flat, [("Ravi", 1000), ("Neha", 500), ("Sam", 500)]) == ["Neha pays Ravi Rs 166.67", "Sam pays Ravi Rs 166.65"]
ravi@laptop:~/projects/settle$ python3 test_settle.py
All tests passed
ravi@laptop:~/projects/settle$ git commit -am "Fix test: per-expense rounding gives 166.65"
ravi@laptop:~/projects/settle$ git log --oneline
4f5d1b9 Fix test: per-expense rounding gives 166.65
2102119 Add test: everyone paid
156f206 Clear error for unknown names
c3a21cb settle v2 + tests

Claude Code checkpoints (docs): "Every prompt you send that starts a turn creates a new checkpoint"; open the rewind menu with /rewind or by pressing Esc twice; restore code, conversation, or both. Limits: "Checkpointing does not track files modified by Bash commands", and it's "Not a replacement for version control". Commit before every agent task.

The final code, run in the compiler

def settle(people, expenses):
    bal = {p: 0 for p in people}
    for payer, amt, *rest in expenses:
        paise = round(amt * 100)
        parts = rest[0] if rest else people
        for name in [payer, *parts]:
            if name not in bal:
                raise ValueError(f"Unknown name: {name}")
        base, extra = divmod(paise, len(parts))
        bal[payer] += paise
        for k, p in enumerate(parts):
            bal[p] -= base + (k < extra)
    debt = sorted([[-b, p] for p, b in bal.items() if b < 0], reverse=True)
    cred = sorted([[b, p] for p, b in bal.items() if b > 0], reverse=True)
    out, i, j = [], 0, 0
    while i < len(debt) and j < len(cred):
        x = min(debt[i][0], cred[j][0])
        rs, ps = divmod(x, 100)
        amount = f"{rs}.{ps:02d}" if ps else f"{rs}"
        out.append(f"{debt[i][1]} pays {cred[j][1]} Rs {amount}")
        debt[i][0] -= x
        cred[j][0] -= x
        i += debt[i][0] == 0
        j += cred[j][0] == 0
    return out

flat = ["Ravi", "Neha", "Sam"]
print(settle(flat, [("Ravi", 1200), ("Neha", 300)]))
print(settle(flat, [("Ravi", 600, ["Ravi", "Sam"])]))
print(settle(flat, [("Ravi", 1000), ("Neha", 500), ("Sam", 500)]))
settle(flat, [("ravi", 500)])
['Sam pays Ravi Rs 500', 'Neha pays Ravi Rs 200']
['Sam pays Ravi Rs 300']
['Neha pays Ravi Rs 166.67', 'Sam pays Ravi Rs 166.65']
Traceback (most recent call last):
  ...
ValueError: Unknown name: ravi

Six rules for working with agents

  1. Commit before every task, so undo is one command.
  2. Allow the least: reading is fine; approve commands one at a time.
  3. Read the last lines of every reply: that's where the confessions are.
  4. Read the diff: small task + big diff = ask why.
  5. Run the tests yourself: "should pass" isn't a result.
  6. Tests can be wrong too: the spec decides.

Common mistakes (real)

What happened What you see Why Fix
nothing approved, run with -p This command requires approval runs and edits need permission approve the exact command, e.g. Bash(python3 test_settle.py)
agent can't run the tests "each one should pass" → AssertionError it traced by hand and got the maths wrong run the tests yourself
"Make all the tests pass" + a wrong test 16 lines added, a new rounding rule it fit the code to the test read the diff; the spec decides; git restore
no commit before the task nothing clean to go back to Git restores only saved versions commit first; /rewind is a backup, not Git

Mini project: run the loop yourself

  1. Make a folder with settle.py (the 22-line version from Episode 4) and test_settle.py (above). git init, git add ., git commit -m "start".
  2. Ask an agent to fix the failing test, approving only edits and python3 test_settle.py.
  3. Read git diff. Accept (commit) or git restore.
  4. Add a wrong test on purpose and ask "make all the tests pass". Read what it changes.
What a good outcome looks like

Step 2: a small diff (about three added lines) that raises ValueError("Unknown name: ..."), and All tests passed from a real run. Step 4: if the agent edits settle.py to fit your wrong test, the diff will be bigger than the task; restore it and fix the test. A great agent reply says the test looks wrong and asks you, instead of changing the rules.

Practice questions

  1. What three things make an agent?
Answer

A language model, tools, and a loop (look, act, check, repeat).

  1. Why can an agent read files freely but must ask before running commands?
Answer

Reading changes nothing; a command can delete files, install programs or send data.

  1. In a diff, what do + and - mean?
Answer

+ is an added line, - is a removed line; lines with no sign are unchanged context.

  1. Why did the model read 5,990 tokens before opening any file?
Answer

The context includes Claude Code's own instructions and the tool definitions, plus the prompt.

  1. An agent edits code to make a test pass, and the diff changes a business rule. What do you do?
Answer

git restore the file, check the spec to decide whether the code or the test is wrong, and fix the wrong one yourself (or tell the agent exactly which).

Quiz

You asked for a one-line fix. The diff says:

 app.js | 214 ++++++++++++++++++++++------------
 3 files changed, 190 insertions(+), 61 deletions(-)

A) Accept it, the tests pass · B) Stop, read the diff and ask why it's so big · C) Delete the project · D) Ask for even more changes

Answer

B. A small task with a big diff is a warning sign. Read it, ask why, and git restore if it went too far.

Interview questions

  1. How does an AI coding agent work? An LLM in a loop with tools: it reads files and runs commands through tools, gets the results back into its context, decides the next action, and repeats until done, under a permission system.
  2. What is a context window? The text the model can see at once (instructions, conversation, tool results), measured in tokens; when it fills, older content is summarised or dropped.
  3. How do you safely let an agent change code? Work in Git, commit first, grant the minimum permissions, review the diff, and run the tests yourself before accepting.
  4. What's the risk of "make the tests pass"? The agent may change the code's behaviour, or the tests, to fit; correct behaviour is defined by the spec, not by whichever side is easier to change.

Glossary

Term Meaning (plain words) Example
Agent an AI program that reads, edits and runs things itself, in a loop Claude Code
Agent loop look → act with a tool → read the result → repeat → report Run 2
Tool an action the agent program performs for the model Read, Edit, Bash, Glob
Bash (tool) runs a terminal command python3 test_settle.py
Permission your approval for a tool or an exact command Bash(python3 test_settle.py)
--allowedTools pre-approves tools/commands in print mode --allowedTools Edit
Permission mode how much the agent may do without asking plan, acceptEdits
Test code that checks other code test_settle.py
assert "this must be true, or stop with an error" assert x == 1
Traceback the list of lines showing where an error happened line 7, in settle
AssertionError the error when an assert is false test 4
ValueError Python error for a bad value Unknown name: ravi
Diff exactly which lines changed between two versions git diff
Hunk header the @@ ... @@ line saying where a change is @@ -3,6 +3,9 @@
Context window all the text the model can see at once; its working memory 1M tokens
Token a piece of text, often a short word or part of one ~6,000 tokens per step
stream-json Claude Code output format that logs every step --output-format stream-json
Checkpoint Claude Code's automatic snapshot before each prompt /rewind, Esc Esc
git restore put a file back to the last commit git restore settle.py
git status --short list changed files (nothing = clean) M settle.py
git diff --stat the size of a change 16 insertions(+), 4 deletions(-)
Regression an old answer changing after an edit Episode 4

Summary

  • An agent = LLM + tools + a loop: look, act, check, repeat, report.
  • Permissions decide which tools and exact commands it may use; agents ask before commands because commands are powerful.
  • A diff shows exactly what changed; read it before accepting.
  • The context window is what the model can see, measured in tokens; it grows with every step.
  • Agents can guess ("should pass") and can change your rules to fit a test. Commit first, read the diff, run tests yourself, undo with git restore (or /rewind, which isn't a replacement for Git).

Next episode: Reading AI-generated code: top-down reading, functions, variables, imports, asking the AI to explain a file, and the "never ship code you can't explain" rule.