claude-code-2026-04-02/docs-site/docs/workflows.md

End-to-end workflows

!!! warning "Recovered source" Behavior described here is inferred from src/; the shipping product may differ by version or build flags.

Interactive terminal session

1. Process start — main.tsx evaluates side-effect imports (profiler, MDM, keychain prefetch), then parses argv with Commander.
2. preAction hook — Trust dialog state, global config, remote-managed settings, policy limits, GrowthBook/feature flags, OAuth/API key paths, MCP official registry prefetch, plugin initialization, and similar steps run before the subcommand handler.
3. REPL launch — replLauncher.tsx creates the Ink root and renders providers (AppState, keybindings, MCP manager, etc.) and mounts screens/REPL.tsx.
4. Input — User typing, paste, voice (if VOICE_MODE), teammate messages, and task notifications enqueue work.
5. Queue — utils/queueProcessor.ts dequeues slash commands and bash lines individually; batches other same-mode items and calls executeInput.
6. Query — query.ts queryLoop streams model output, schedules tool calls, applies permission checks, and updates transcript state.
7. Tools — services/tools/toolExecution.ts / StreamingToolExecutor and per-tool modules under tools/* perform filesystem, shell, web, MCP, and agent operations.
8. Compaction — When context limits approach, services/compact/* reduces history per compaction policy.

Official parallels: Interactive mode, How Claude Code works.

Print mode / stream-json / programmatic control

1. Routing — main.tsx selects the print/headless path instead of the full REPL when -p / related flags are used.
2. Structured I/O — cli/structuredIO.ts parses lines into typed events; cli/print.ts runHeadlessStreaming runs the async loop that consumes user/control messages and emits stdout messages.
3. Engine — QueryEngine.submitMessage builds processUserInputContext for non-interactive sessions and streams SDK-style messages.

Official parallels: Run Claude Code programmatically, Agent SDK overview (external platform docs).

Teammates / agent teams

1. Spawn — Swarm backends (utils/swarm/backends/*) create tmux panes, iTerm panes, or in-process runners.
2. Teammate loop — utils/swarm/inProcessRunner.ts runs a while loop: build prompt messages, check compaction/token limits, call into shared query/tool paths, sync permissions via leaderPermissionBridge, etc.
3. REPL integration — REPL.tsx wires useInboxPoller, useMailboxBridge, and handleIncomingPrompt so teammate messages become user turns.

Official parallels: Agent teams, Subagents.

Hooks (user-configured)

1. Session start — utils/sessionStart.ts processSessionStartHooks / processSetupHooks run after configuration is known; wired from startup paths in main.tsx and related modules.
2. Per-event hooks — Additional hook types align with the schema described in the official Hooks reference; implementation is spread across hook runners and tool lifecycle code.

Official parallels: Hooks guide, Hooks reference.

Compaction and context

1. Triggers — Token estimation and session memory modules decide when to compact.
2. Pipeline — services/compact/compact.ts, autoCompact.ts, microCompact.ts, and related files rewrite or summarize message history.
3. Post-compact — Cleanup hooks update UI and storage.

Official parallels: Context window, Checkpointing, Costs.

MCP and external tools

1. Config — services/mcp/config.ts, env expansion, enterprise allowlists.
2. Connection — MCPConnectionManager.tsx, stdio and SDK transports.
3. Tool surface — tools/MCPTool, ReadMcpResourceTool, ListMcpResourcesTool, McpAuthTool.

Official parallels: MCP, Channels.

Optional sequence (interactive turn)

sequenceDiagram
  participant User
  participant REPL as REPL.tsx
  participant Queue as queueProcessor
  participant Query as queryLoop
  participant API as services/api
  participant Tool as tools/*
  User->>REPL: input / slash command
  REPL->>Queue: enqueue
  Queue->>REPL: executeInput
  REPL->>Query: onQuery messages
  Query->>API: stream completion
  API-->>Query: tool_use
  Query->>Tool: execute
  Tool-->>Query: result
  Query-->>REPL: update transcript