# How Claude Code works

The agentic loop in Claude Code, traced on a hello world task, with the built-in tools, permission prompts, context, sessions and undo you meet first.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work/claude-code

## At a glance

| | Claude Code |
|---|---|
| Term | Agentic loop: gather context, take action, verify results. The surrounding layer that supplies tools and manages context is the agentic harness |
| Configured in | Settings files: `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, managed settings; per session with flags and `/` commands |
| Loads / runs | The loop starts when you send a prompt and repeats until Claude answers without a tool call or you interrupt |
| Scope & precedence | Managed > command-line flags > project local > shared project > user. List keys such as `permissions.allow` merge across files |

## Build the scenario

Run `claude` in an empty folder and send the prompt from the [example scenario](https://ai-sw-factory.mellicci.dev/fundamentals/how-coding-agents-work/example-scenario):

```text
Create a hello world app in Python and run it.
```

| Turn | What Claude decides | Built-in tool | Prompt in Manual mode |
|---|---|---|---|
| 1 | Write the file | `Write` (creates `hello.py`) | Yes, approve the file edit |
| 2 | Run it | `Bash` (`python hello.py` or `python3 hello.py`) | Yes, approve the command |
| 3 | Report the output | None, plain text | None |

Claude may add `Read`, `Glob` or `Grep` calls first. Those need no approval inside the working directory. On a machine with only `python3`, turn 2 fails with exit 127, the error becomes context, and Claude retries.

Check the context after the run:

```text
/context
```

It shows a colored grid of what fills the window, with optimization suggestions. Undo the file with `/rewind`.

The same task without a person at the keyboard:

```bash
claude -p "Create a hello world app in Python and run it." --allowedTools "Write,Bash(python *)"
```

`-p` prints the answer and exits. `--allowedTools` pre-approves the two tools, because nobody can answer a prompt.

<note>

Recent versions start terminal sessions in auto mode, where a classifier reviews actions instead of asking you. To see the prompts above, start with `claude --permission-mode default`, or press `Shift+Tab` to switch to Manual.

</note>

## Specifics

### Built-in tools that matter first

| Tool | What it does | Asks in Manual mode |
|---|---|---|
| `Read` | Reads file contents | No |
| `Glob` / `Grep` | Finds files by pattern / searches file contents | No |
| `Edit` | Targeted edits to an existing file | Yes |
| `Write` | Creates or overwrites a file | Yes |
| `Bash` | Runs a shell command, each in a separate process | Yes |
| `WebFetch` / `WebSearch` | Fetches a URL / searches the web | Yes |
| `Agent` | Starts a subagent with its own context window | No |

The documentation lists many more, and notes `Glob` and `Grep` are absent by default on macOS, Linux and WSL. Tool names are the exact strings used in permission rules and hook matchers. MCP servers add tools, and skills run through the `Skill` tool.

### Models

| Action | How |
|---|---|
| Switch mid-session | `/model <alias or name>`, or `/model` for a picker |
| Start with one | `claude --model <alias or name>` or `ANTHROPIC_MODEL` |
| Set a default | `model` in settings; `/model` saves your choice there |

Aliases include `default`, `best`, `fable`, `sonnet`, `opus`, `haiku` and `opusplan` (Opus in plan mode, Sonnet for execution). Resumed sessions keep their saved model unless you pass `--model`.

### Context window and compaction

| | Behavior |
|---|---|
| Holds | History, file contents, command output, `CLAUDE.md`, memory, loaded skills, system instructions |
| Automatic | Near the limit, clears older tool output first, then summarizes; early detailed instructions may be lost |
| Manual | `/compact [focus]` summarizes now; `/autocompact <tokens>` sets how full the window gets first; `/clear` starts empty |
| Inspect | `/context` |

### Sessions and undo

| Need | Command |
|---|---|
| Reopen the latest conversation in this directory | `claude --continue` |
| Pick or name a session | `claude --resume [name]`, `/resume`, `claude -n <name>`, `/rename` |
| Branch without changing the original | `/branch` or `--fork-session` |
| Undo edits or conversation | `/rewind`, or `Esc` twice on an empty prompt |

Each prompt that starts a turn creates a checkpoint, and the 100 most recent keep file snapshots. A new session starts with a fresh context window.

### Permission modes at a glance

| Mode | Runs without asking |
|---|---|
| `default` (Manual) | Reads only |
| `acceptEdits` | Reads, file edits, common filesystem commands |
| `plan` | Reads; no source edits until you approve a plan |
| `auto` | Everything, with classifier checks |
| `dontAsk` | Pre-approved tools only; the rest is denied |
| `bypassPermissions` | Everything; isolated containers and VMs only |

Depth: [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model).

### Interactive vs non-interactive

| | Interactive `claude` | `claude -p` |
|---|---|---|
| Approvals | Prompts you | Pre-approve with `--allowedTools` or a mode |
| Sessions | Listed in the picker | Left out of the picker and `--continue`; resume by ID |

More in [headless execution](https://ai-sw-factory.mellicci.dev/fundamentals/headless-execution).

## Gotchas

- Checkpoints cover only edits made by Claude's file tools. Files changed by `Bash` (`rm`, `mv`, `cp`), by subagents, or outside Claude Code are not restored. Use git for those.
- Instructions from early in a long conversation can be lost when it is summarized. Put persistent rules in `CLAUDE.md`.
- The starting permission mode depends on the version and plan, and on the surface (`claude -p` starts in `default`, or in `auto` when feature-flag fetching is off, such as on a third-party provider). Check the mode indicator before you expect prompts.
- Environment variables set by one `Bash` call do not persist to the next, because each command runs in a separate process.
- `claude -p` runs a project's committed hooks and MCP servers without a trust dialog unless you pass `--bare`.