This is the per-subsystem status index for the Python port of Claude Code.
Phase 1 (the agentic core) is implemented and tested. It is a working,
offline-testable port of the minimal viable agent: the streaming agentic loop,
the Tool contract, tool orchestration/execution, the four-phase permission
system, the built-in tools, and the CLI REPL.
Everything else is currently a scaffolded structural mirror of the
original src/ tree — importable Python skeletons whose public interfaces carry
real, type-hinted signatures (snake_case, with the original camelCase noted in
docstrings) but whose bodies raise NotImplementedError("Phase N: see <ts path>").
Pure data carriers (dataclasses, enums, constants) are real. Each scaffolded
module/package opens with a docstring naming its TS source(s) and its
Status: scaffolded (Phase N). marker.
The work follows the five-phase refactor roadmap in
../claude-code/ARCHITECTURE_ANALYSIS.md
(§11). See the Roadmap section below for the phase summary.
These modules contain real, working implementations (not stubs):
| Module | Purpose |
|---|---|
claude_code/query/loop.py |
Streaming agentic loop: callModel → collect tool_use → run tools → splice results → recurse; tool_use/tool_result pairing invariants and interrupt handling. |
claude_code/query_engine.py |
QueryEngine driver wrapping the loop for a session. |
claude_code/tool.py |
The Tool contract (execution + behavior flags + permission) and build_tool. |
claude_code/services/tools/orchestration.py |
Tool-batch orchestration (serial + concurrency-safe slicing). |
claude_code/services/tools/execution.py |
Per-tool execution and result shaping. |
claude_code/model/anthropic_client.py |
Anthropic streaming model layer. |
claude_code/permissions/ |
Four-phase, fail-closed permission system. |
claude_code/tools/ |
Built-in tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite. |
claude_code/tools_registry.py |
Tool registration / lookup. |
claude_code/context.py |
Tool-use context / dependency injection. |
claude_code/task.py |
Task base abstraction. |
claude_code/session_storage.py |
Session persistence. |
claude_code/cli.py |
Interactive CLI REPL (Renderer, _run_turn, headless/print path). |
Tests: the Phase-1 suite (tests/) is designed to pass 38 tests offline
(no network). Files: test_model_layer.py, test_orchestration.py,
test_permissions.py, test_query_engine.py, test_query_loop.py,
test_schema.py, test_tools.py, test_tool_contract.py.
Known issue (introduced by scaffolding): the Phase-5
cli/package (claude_code/cli/__init__.py) now sits as a sibling of the Phase-1cli.pymodule. Python resolves the package over the module, sofrom claude_code.cli import Renderer, _run_turnfails andtests/test_query_engine.pycurrently errors at import (the other 35 tests still pass). Resolve before relying on the suite — e.g. rename the scaffolded package (claude_code/cli_app/) or fold the Phase-1 REPL into the package.
Every row below is an importable skeleton mirroring its TS source. Grouped by roadmap phase.
| Python package | TS source | Phase | Purpose |
|---|---|---|---|
claude_code.hooks (+ .executors, .tool_permission) |
src/utils/hooks.ts, src/utils/hooks/*, src/hooks/toolPermission/, useCanUseTool.tsx |
2 | Lifecycle-hook engine: 27 hook events, declarative hook config variants, per-event async dispatchers, and the can-use-tool permission bridge. |
claude_code.services.api |
src/services/api/ |
2 | Deep transport/retry/error tier under the streaming wrapper: retry/fallback, error classification, multi-provider client factory, prompt dumping, API logging. |
claude_code.services.analytics |
src/services/analytics/ |
2 | Event logging (queue-until-sink, no-PII), metadata enrichment, GrowthBook feature flags, Datadog/first-party sinks, opt-out checks. |
claude_code.utils (new leaves + .hooks, .model) |
src/utils/ (tokens, tokenBudget, thinking, cwd, errors, path, format, file, fileStateCache, attachments, permissions/filesystem) |
2 | Agentic-core utility families: token accounting/budget, thinking config, contextvar cwd, error hierarchy, path/format/file IO, attachments. |
claude_code.constants |
src/constants/ (apiLimits, files, tools, querySource) |
2 | API/media limits, binary-extension detection, tool allowlists, query-source taxonomy. |
claude_code.schemas |
src/schemas/hooks.ts |
2 | Hook config validation dataclasses. |
claude_code.entrypoints (+ .sdk) |
src/entrypoints/, src/entrypoints/sdk/ |
2 | Public Agent SDK surface: tool/server helpers, query/session protocols, serializable/runtime/control-protocol type split. |
claude_code.types.* (hooks, command, logs, plugin, tools) |
src/types/ |
2 | Standalone type stubs added alongside the existing Phase-1 types/. |
claude_code.bootstrap |
src/state.ts (bootstrap slice) |
2 | Process-global State dataclass + STATE singleton + representative accessors. |
| Python package | TS source | Phase | Purpose |
|---|---|---|---|
claude_code.tools (37 remaining tool stubs) |
src/tools/* |
3 | Every remaining built-in tool: Agent(=Task), NotebookEdit, WebFetch, WebSearch, AskUserQuestion, Skill, Enter/ExitPlanMode, Enter/ExitWorktree, Task* (Create/Get/Update/List/Output/Stop), SendMessage, Team*, LSP, MCP-resource tools, ToolSearch, Config, Brief, Sleep, PushNotification, Monitor, Cron*, RemoteTrigger, Snip, CtxInspect, Workflow, StructuredOutput, PowerShell. |
| Python package | TS source | Phase | Purpose |
|---|---|---|---|
claude_code.coordinator |
src/coordinator/coordinatorMode.ts |
4 | Coordinator/Swarm mode: mode detection, worker-tools context injection, coordinator system prompt. |
claude_code.tasks (+ local_shell/local_agent/remote_agent/in_process_teammate/dream subpackages) |
src/tasks/ |
4 | Task kinds for the orchestration layer: backgrounded shells, forked local/remote agents, in-process teammates, dream consolidation, plus shared task state/stop/pill-label helpers. |
claude_code.memdir |
src/memdir/ |
4 | Persistent memory directory: four-type taxonomy, memory age/staleness, path resolution + gating, single-pass scan, relevance selection, MEMORY.md truncation. |
claude_code.services.session_memory |
src/services/SessionMemory/ |
4 | Session-memory extraction: trigger logic, post-sampling hook init, forked-agent extraction, prompts. |
claude_code.services.auto_dream |
src/services/autoDream/ |
4 | Background memory consolidation: enablement gate, lock-file mutex, four-stage consolidation prompt, time/session/lock runner firing a DreamTask. |
claude_code.services.extract_memories |
src/services/extractMemories/ |
4 | Turn-end forked memory extraction + shared auto-mem tool gate + drain-before-shutdown. |
This port targets third-party APIs only and authenticates solely via a model API key / base URL. The following originally-mirrored subsystems and commands were removed because they require an official Claude/Anthropic account login, subscription, or Anthropic-hosted infrastructure:
claude_code.bridge/— claude.ai cross-device REPL/remote bridge (+ its trusted-device/JWT auth).claude_code.remote/— Anthropic CCR remote-session client.claude_code.cli.handlers.auth— claude.ai OAuth login/logout/status.claude_code.services.mcp.claudeai— the claude.ai MCP proxy transport.claude_code.services.mcp.xaa/— cross-app-access IdP login + token exchange.- ~30 slash commands (login/logout/oauth-refresh, upgrade, extra-usage,
rate-limit-options, share, teleport, desktop/mobile, install-github/slack-app,
remote-env/web-setup, ultraplan/ultrareview, feedback/stickers, …) — see
commands/manifest.py::EXCLUDED_BOUND_TO_ANTHROPIC.
| Python package | TS source | Phase | Purpose |
|---|---|---|---|
claude_code.cli (+ .handlers, .transports) |
src/cli/ |
5 | CLI structural mirror: structured/remote NDJSON IO, headless print driver, self-update, command handlers (agents/mcp/plugins/auto — no auth/login), and transports (WS/SSE/hybrid + uploaders). The Phase-1 REPL entrypoint lives at claude_code/repl.py (no collision). |
claude_code.commands |
src/commands/, src/types/command.ts |
5 | Slash-command registry + type model (prompt/local/local-jsx union), factory helpers, a 99-entry command manifest, and representative command stubs. |
claude_code.components (+ design_system, spinner, messages, prompt_input, permissions, dialogs) |
src/components/ |
5 | React/Ink terminal UI tree mirror with an Ink→rich/textual mapping; a manifest of 11 component groups (6 scaffolded, 5 recorded-only). |
claude_code.ink (+ 11 subpackages) |
src/ink/, src/screens/, src/keybindings/, src/vim/, src/voice/, src/outputStyles/ |
5 | Custom Ink renderer (dom/reconciler/renderer/layout/termio), screens, context-aware keybinding resolver, vim state machine, voice gating, output styles. |
claude_code.services.mcp (+ .channels) |
src/services/mcp/ |
5 | Model Context Protocol: transport configs, multi-scope config, client connect/tools/resources, OAuth to third-party MCP servers (claude.ai proxy + xaa cross-app-access removed), elicitation, channel allowlist/notification/permissions. |
claude_code.services.lsp |
src/services/lsp/ |
5 | LSP subsystem: JSON-RPC client → server instance → manager → process singleton; extension routing, file sync, diagnostic registry + passive feedback. |
claude_code.skills (+ .bundled) |
src/skills/ |
5 | Skill discovery, frontmatter parsing, bundled-skill registry, MCP skill builders. |
claude_code.plugins (+ .bundled) |
src/plugins/, src/types/plugin.ts, src/services/plugins, src/utils/plugins |
5 | Plugin manifest/load model, builtin registry, marketplace manager, install/enable operations, trust policy gating. |
claude_code.migrations |
src/ settings migrations |
5 | One-shot idempotent settings migrations + run_all_migrations. |
claude_code.server |
local direct-connect server | 5 | create_direct_connect_session + DirectConnectManager + session/config types. |
claude_code.upstreamproxy |
CCR upstream proxy | 5 | Container-side MITM proxy wiring + CONNECT→WebSocket relay (fail-open). |
claude_code.native_ts (+ .yoga_layout) |
former native modules | 5 | Pure-Python ports: nucleo fuzzy file index, color diff, Yoga layout enums/engine. |
claude_code.buddy |
src/buddy/ |
5 | Terminal Tamagotchi easter egg (deterministic seeded roll; unrelated to core). |
claude_code.assistant |
claude assistant history | 5 | Paginated remote session history fetch. |
claude_code.moreright |
external REPL hook | 5 | No-op REPL hook stub interface. |
Summarized from ../claude-code/ARCHITECTURE_ANALYSIS.md §11.
-
Phase 1 — minimal viable agent core (≈
query.ts+Tool.ts+toolOrchestration.ts): theToolcontract (execution + behavior flags + permission) andbuildTool; the streaming agentic loop (callModel → collect tool_use → runTools serially → splice back → recurse); tool_use/tool_result pairing invariants and interrupt handling. (Implemented.) -
Phase 2 — robustness:
ToolUseContextdependency injection; concurrency-safe batch slicing; streaming tool executor (run-while-streaming); four-phase permissions with fail-closed defaults; lifecycle hooks; model fallback with withhold-then-recover. -
Phase 3 — long-horizon execution: three-level context compaction; tool-result spill-to-disk budgeting; prompt-cache safety (system/user context separation + stable ordering).
-
Phase 4 — multi-agent & memory:
Taskabstraction + AgentTool (fork sub-agents, worktree isolation); task-control tool surface + SendMessage; persistent memory directory + SessionMemory extraction + Dream consolidation. -
Phase 5 — ecosystem: MCP / LSP integration; Skills / slash commands / plugins; remote sessions (CCR / ULTRAPLAN).
| Codename | Meaning |
|---|---|
| Tengu | Internal codename for Claude Code (analytics events are tengu_*). |
| KAIROS | Always-on proactive assistant (Sleep/Brief/PushNotification tools). |
| ULTRAPLAN | Remote Opus deep-planning offload. |
| Dream / autoDream | Background memory-consolidation sub-agent. |
| Coordinator / Swarm | Multi-worker orchestration mode. |
| CCR | Cloud Code Runtime — remote agent execution environment. |
| Buddy | Terminal Tamagotchi easter egg (src/buddy/, unrelated to core). |