AX-Copilot/docs/claude-code-docs-main/en/concepts/how-it-works.md

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:

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. 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). 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. 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). Approved tool calls run. Results — file contents, command output, search hits — are appended to the conversation as `tool_result` blocks. 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. 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).

Context loading

At the start of each conversation, Claude Code builds two context blocks that are prepended to every API call:

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.

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.

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 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

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

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

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.

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.