Stage 1 of 11

How a coding agent actually works

The agent re-reads one context window every turn, and that window is all it knows. A rule typed into the chat fades from it; a rule in a file keeps coming back.

15 min read 30 min exercise Plaque: Loop Reader

In 30 seconds

An agent is a loop: read the context, pick a tool call, get the result, repeat.
Rules in files survive long sessions. Rules typed in chat can be summarised away.
The harness sits between the model and your machine, so that's where actions can be blocked.

What happened

Failed run

A developer kept every rule in a 17,000-character chat prompt across a 356-turn session. The rules file (CLAUDE.md) was written at the very end, so it steered nothing.

Near the end, the agent committed without being asked. The developer: "i did not want u to commit anything until I say so".

A real session, anonymised · Claude Code

With the harness

The rules live in a file the tool loads at the start of every session and re-reads after compaction.

"Don't commit without asking" becomes a rule the tool enforces: it has to ask you first, whatever the agent remembers.

That's the whole course: move each rule out of the chat and into a layer that can't forget it.

The loop

An agent is a model in a loop with tools: functions it may call, like read a file, edit a file or run a command (How Claude Code works). Watch one turn:

Two things follow. Apart from its training, the model knows only what is in that window. And because every tool call passes through the harness, the harness is where you can block, not just ask.

Managing the context window

The context window is the model's working memory, and it has a size limit. When it fills up, Claude Code compacts it: older conversation is replaced by a short summary. Try it:

Context window

0% full

rules file (re-read from disk) rule typed in chat messages and tool results

So: a rule that matters goes in a file, never only in chat. And you choose what happens to the window, instead of waiting for automatic compaction:

When	Do this	Why
Same task, but the window is getting full	`/compact keep the order-slice decisions and the failing test`	You stay in the task, and the summary keeps what you name instead of what the automatic pass guesses
A new, unrelated task	Start a new chat: `/clear` (same as `/new`), or quit and run `claude` again	The old conversation would only crowd out what the new task needs. It isn't deleted: `/resume` brings it back
Big research or many file reads	Ask for a subagent (lesson 6)	Its reads fill its own window; only a summary comes back to yours
Any time	`/context`	Shows what is using the space right now

What would you do?

Four situations from a normal day. Pick the move before you look at the answer.

Two hours into the low-stock endpoint, the agent re-reads files it already read and forgets the threshold you agreed. The task isn't done.

Same task, a crowded window: /compact keep the threshold decision and the failing test. You name what the summary must keep, instead of letting the automatic pass guess.

The endpoint is done and committed. Next you want to fix an unrelated typo in the README.

Nothing in the old chat helps with the README, and it would only crowd the window. A new chat starts clean; /resume still has the old one.

Twenty minutes in, the agent is on track and following your rules. The window is less than half full.

Nothing is wrong, so change nothing. Every summary or fresh start loses some detail; carrying on is the only move that keeps the conversation exactly as it happened.

Answers are getting vague after a long session. Before you choose anything, you want to see whether old test output is what's taking up the space.

/context shows what fills the window right now. Look first, then pick: compact if it's the same task, a new chat if it isn't.

Two more moves, for when work has to leave this chat (hand it to a new session, or fork a side task), come in lesson 5, once you know what a skill is.

Going deeper: exactly what survives compaction

From the docs (Context window, verified 2026-10-01):

Re-read from disk: the project-root CLAUDE.md or AGENTS.md, unscoped rules, auto memory, and the plan from plan mode.
Reloaded only when a matching file is read again: rules with paths: and nested rules files. To make a rule survive, keep it in the root file.
Re-injected but capped: skills you used, 5,000 tokens each. Put a skill's most important lines at the top.
Up to five recently edited files are re-read. Everything else in the conversation becomes the summary.

You can also set when it happens (/autocompact) or summarise part of a conversation with /rewind.

Which mode are you in?

A permission mode decides which actions run without asking you. Press Shift+Tab to cycle through them (Permission modes).

defaultAsks before almost everything ("Manual")

acceptEditsEdits files freely, asks for commands

planReads and plans; no edits until you approve

autoA second model approves most actions

bypassNever asks. Sandboxes only

Asks you moreAsks you less

On Claude Code v2.1.283 or later you start in auto verified 2026-09-30. That is why a commit or an app launch can happen with no prompt, unless your repo says otherwise: an ask rule in its permission settings still prompts even in auto mode, whatever the model decides. Lesson 7 writes those.

Going deeper: deny rules, ask rules, and a clicked-together allow list

Two things hold in every mode. A deny rule in your settings always blocks, and an ask rule still prompts "even in auto mode" (Permissions). Lesson 7 writes both.

Clicking "Yes, and don't ask again" saves an allow rule to your personal .claude/settings.local.json. One developer copied a pile of those into the shared .claude/settings.json, including rules that let the agent rewrite git history, and called it their "AI configuration". An allow list you clicked together isn't a policy.

	Claude Code	Codex	Antigravity
Approval	Permission modes	`approval_policy`: `on-request`, `never`, `auto_review` verified 2026-09-30	Presets: Default, Request Review, Turbo
Plan first	Plan mode or a `/plan` prefix	Ask for a plan in a read-only sandbox	`/plan` makes an Implementation Plan

Sources: Codex approvals · Antigravity permissions

New to the words? Five you'll meet all course

Harness: the agent tool plus the files in your repo that configure it.
Rule: an instruction in a file the agent reads, so it doesn't depend on chat.
Skill: a saved, named procedure the agent follows when called.
Reviewer: a second agent that checks the first one's work with fresh eyes.
Hook or guard: something that blocks an action before it runs, instead of asking nicely.

All terms: glossary.

Check yourself

You told the agent in chat, 200 turns ago, "never commit without asking". It just committed. What is the most likely cause?

Chat instructions get summarised during compaction; only files like AGENTS.md are re-read from disk. Auto mode then let the commit run. Even a remembered instruction is only a request, so lesson 7 makes "ask before commit" a rule the harness enforces.

Where can a tool call be stopped regardless of what the model "wants"?

Everything the model reads is a request. The harness runs the call (step 4 in the diagram), so that's where permission rules and hooks can refuse it.

A developer commits .claude/settings.local.json full of approvals they clicked. What is it?

"Don't ask again" writes to settings.local.json, which is personal and meant to stay out of git. A policy is written on purpose, reviewed, and lives in .claude/settings.json.

Practice first

Quick drills with instant feedback on this lesson's ideas, before you touch the repo.

A developer wrote down how they think their agent session works. Click the lines that get it wrong.

Each turn, the model reads the whole context window before it acts.
I said "never commit" in chat on turn 3, so it holds for the whole session.
After compaction, the project-root AGENTS.md is re-read from disk.
Plan mode lets it edit files freely; it only asks before commands.
/clear starts a new chat, and /resume can bring the old one back.
Auto mode: a second model approves most actions.
My rules file is enforced by the harness, so the agent can't break it.
A deny rule in settings blocks the action in every mode.

What would you do?

You want the agent to read ProductsController and propose how to add the low-stock endpoint, without touching a single file yet. Which permission mode?

Plan mode reads and plans, with no edits until you approve. acceptEdits edits freely, auto lets a second model approve most actions, and bypass never asks.

For the third session in a row you type "run dotnet test before you say done". Where should that sentence live?

A file in the repo loads at the start of every session and is re-read after compaction. Anything you type twice is a candidate for the harness.

In auto mode the agent ran git commit without asking, though your rules file says to ask first. What actually makes it stop and ask next time?

Everything the model reads is a request. The harness checks every call, and an ask rule still prompts even in auto mode. Lesson 7 writes these.

Exercise: set up the repo, then watch a chat rule vanish

Exercise · about 30 min · you add: a git repo with your work identity

Get the two repos into one folder. Windows: use WSL2 or Git Bash (setup).

mkdir -p ~/projects && cd ~/projects
git clone https://github.com/OsmosysSoftware/agent-harness-course.git
git clone https://github.com/OsmosysSoftware/agent-harness-practice.git stockapi
cd stockapi && rm -rf .git

The last line drops the template's history, so your repo starts clean.

Start your own history under your work identity:
```
git init -b main
git config user.name "Your Name"
git config user.email you@yourcompany.com
git add . && git commit -m "chore: import StockApi starter"
```
Commit messages in this course use Conventional Commits: type(scope): summary, where type is feat, fix, docs, test, refactor or chore.
Check it builds: dotnet build, then dotnet test (4 tests, green).
Start Claude Code in the repo. Press Shift+Tab until it says plan mode on. Then type /output-style explanatory: Claude does the same work and adds short Insight notes on why. (That is an output style; lesson 2 shows them all.)
Ask: "Explain how an order reduces stock in this repo, citing file:line." Then run /context to see what fills the window.
The drift test. Say "From now on, end every answer with STOCK-OK." Ask anything and check it complies. Run /clear to start a new chat and ask again: the rule is gone. (Still there? Run /memory: auto memory saved it to a file, which proves the point.)
Write one sentence: where would that rule have to live to survive? Lesson 2 puts it there.

Codex: run codex with default approvals. Antigravity: open the folder with the Default preset. In step 6, start a new conversation instead of running /clear.

Done when: tick all three to earn the Loop Reader plaque

git log --format='%an <%ae>' shows your work email
dotnet test is green
You saw STOCK-OK disappear after /clear

Worth installing or reading

Context window explorer: Anthropic's interactive simulation of what loads into the window and what each file read costs.
/context and /usage: Built in. /context shows what fills the window right now; /usage shows cost and plan limits.

Each link has its own install steps. Install only what you will use, check how recent it is, and read what a plugin adds before you enable it. Links checked 2026-10-01.

Harness it

Anything you type twice is a candidate for the harness. Keep a list this week of what you repeat to the agent; lesson 2 gives the first items a home.