126 lines
7.3 KiB
Markdown
126 lines
7.3 KiB
Markdown
> ## Documentation Index
|
|
> Fetch the complete documentation index at: https://vineetagarwal-code-claude-code.mintlify.app/llms.txt
|
|
> Use this file to discover all available pages before exploring further.
|
|
|
|
# How Claude Code works
|
|
|
|
> The agentic loop, context loading, tool execution model, and conversation lifecycle under the hood.
|
|
|
|
Claude Code is a terminal-based coding agent that runs a continuous agentic loop: it reads your request, reasons about what to do, calls tools, observes results, and repeats until the task is complete or it needs your input.
|
|
|
|
## The agentic loop
|
|
|
|
Every interaction follows the same fundamental cycle:
|
|
|
|
<Steps>
|
|
<Step title="User sends a message">
|
|
You type a message in the terminal (interactive mode) or pass one via `--print` / stdin (non-interactive / headless mode). The message is appended to the conversation history.
|
|
</Step>
|
|
|
|
<Step title="Context is assembled">
|
|
Before calling the model, Claude Code assembles a system prompt that includes: the current date, git status (branch, recent commits, working-tree status), any loaded CLAUDE.md memory files, and the list of available tools. This context is built once per conversation and memoized — see [`context.ts`](/concepts/memory-context).
|
|
</Step>
|
|
|
|
<Step title="Claude reasons and selects tools">
|
|
The assembled conversation is sent to the Anthropic API. The model reasons about the task and emits one or more `tool_use` blocks — each specifying a tool name and structured JSON input.
|
|
</Step>
|
|
|
|
<Step title="Permission check">
|
|
Before executing each tool call, Claude Code evaluates the current permission mode and any allow/deny rules. Depending on the mode, it either auto-approves, prompts you for confirmation, or blocks the call entirely. See [Permissions](/concepts/permissions).
|
|
</Step>
|
|
|
|
<Step title="Tool executes and returns a result">
|
|
Approved tool calls run. Results — file contents, command output, search hits — are appended to the conversation as `tool_result` blocks.
|
|
</Step>
|
|
|
|
<Step title="Loop continues">
|
|
The model receives the tool results and either calls more tools or produces a final text response. The loop repeats until no tool calls remain in a model turn.
|
|
</Step>
|
|
</Steps>
|
|
|
|
<Note>
|
|
The loop runs entirely in your terminal process. There is no remote execution server — your files, shell, and credentials never leave your machine unless a tool explicitly sends them (e.g., `WebFetch`, `WebSearch`, or an MCP server).
|
|
</Note>
|
|
|
|
## Context loading
|
|
|
|
At the start of each conversation, Claude Code builds two context blocks that are prepended to every API call:
|
|
|
|
<Tabs>
|
|
<Tab title="System context">
|
|
Assembled by `getSystemContext()` in `context.ts`. Contains:
|
|
|
|
* **Git status** — current branch, default/main branch, git username, `git status --short` output (truncated to 2 000 characters if larger), and the last 5 commits from `git log --oneline`.
|
|
* **Cache-breaking injection** — an optional ephemeral string used internally to bust the server-side prompt cache during debugging.
|
|
|
|
Git status is skipped when `CLAUDE_CODE_REMOTE=1` is set (remote/cloud mode) or when git instructions are disabled in settings.
|
|
</Tab>
|
|
|
|
<Tab title="User context">
|
|
Assembled by `getUserContext()` in `context.ts`. Contains:
|
|
|
|
* **CLAUDE.md memory** — all memory files discovered by the 4-level hierarchy (managed → user → project → local). Disabled by `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1` or in bare mode without explicit `--add-dir`. See [Memory & context](/concepts/memory-context).
|
|
* **Current date** — injected as `Today's date is YYYY-MM-DD` so the model always knows the date.
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Both context blocks are **memoized** for the duration of the conversation using `lodash/memoize`. Calling `setSystemPromptInjection()` clears the caches immediately.
|
|
|
|
## Tool execution model
|
|
|
|
Claude Code does not execute tool calls autonomously by default. Each tool has a `checkPermissions` method, and the result determines what happens next:
|
|
|
|
| Permission result | What happens |
|
|
| ----------------- | ------------------------------------------------------ |
|
|
| `allow` | Tool runs immediately, result appended to conversation |
|
|
| `ask` | Claude Code pauses and renders a confirmation dialog |
|
|
| `deny` | Tool call is rejected; Claude receives an error result |
|
|
|
|
The permission behavior is controlled by the active [permission mode](/concepts/permissions) and any configured allow/deny rules. In `bypassPermissions` mode all checks are skipped. In `acceptEdits` mode file-edit tools are auto-approved but bash commands still prompt.
|
|
|
|
Tool calls that are safe and read-only (e.g., `Read`, `Glob`, `Grep`) are generally auto-approved across all modes.
|
|
|
|
## Interactive vs. non-interactive (task) mode
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Interactive (REPL) mode" icon="terminal">
|
|
The default experience. Claude Code renders a live terminal UI using React/Ink. You see streaming output, tool-use confirmations, and spinner animations as the agent works. Messages persist across the session until you exit.
|
|
</Card>
|
|
|
|
<Card title="Non-interactive / print mode" icon="file-code">
|
|
Activated with `--print` or by piping stdin. No UI is rendered. Output is written to stdout so it can be captured by scripts or CI pipelines. Useful for one-shot automation tasks.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
### Sub-agents (Task tool)
|
|
|
|
Claude can spawn sub-agents via the `Task` tool (`AgentTool`). Each sub-agent runs its own nested agentic loop with an isolated conversation and, optionally, a restricted tool set. Sub-agents can run locally (in-process) or on remote compute. Results are returned to the parent agent when the sub-agent completes. See [Tools](/concepts/tools) for details.
|
|
|
|
## Conversation storage and resumption
|
|
|
|
Conversations are stored as JSON transcript files on disk (in `~/.claude/` by default). Each conversation has a unique session ID. You can resume a previous conversation with `--resume <session-id>` or pick from the list with `--resume` alone.
|
|
|
|
When a conversation is resumed:
|
|
|
|
* The full message history is loaded from disk.
|
|
* Memory files are re-discovered and may differ from when the conversation was first started.
|
|
* The permission mode resets to the configured default unless it was persisted in the session.
|
|
|
|
<Tip>
|
|
Long conversations are periodically **compacted** — the oldest messages are summarised to keep the context window manageable. The full raw transcript is always preserved on disk; compaction only affects what is sent to the API.
|
|
</Tip>
|
|
|
|
## The query engine
|
|
|
|
Under the hood, each "turn" in the agentic loop is driven by a **query** — a call to `query.ts` that sends the current message list to the Anthropic API and streams back the response. The query engine handles:
|
|
|
|
* Streaming token output to the terminal in real time.
|
|
* Dispatching `tool_use` blocks to the appropriate tool handlers.
|
|
* Enforcing per-turn token and tool-call budgets.
|
|
* Collecting tool results and appending them before the next model call.
|
|
* Triggering compaction when the context window fills up.
|
|
|
|
Each tool has a `maxResultSizeChars` property. When a result exceeds this limit the content is saved to a temporary file and the model receives a preview with the file path, preventing context-window overflow from large outputs.
|
|
|
|
|
|
Built with [Mintlify](https://mintlify.com). |