Skip to main content
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:
1

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

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

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

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

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

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.
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.
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 resultWhat happens
allowTool runs immediately, result appended to conversation
askClaude Code pauses and renders a confirmation dialog
denyTool 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

Interactive (REPL) 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.

Non-interactive / print mode

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.