> ## 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).