Claw Code 아키텍처: 이중 레이어 에이전트 하네스 설계

아키텍처 개요

Claw Code 아키텍처는 이중 레이어 설계를 따릅니다: : 에이전트 세션, 명령어 라우팅, LLM 상호작용을 관리하는 Python 오케스트레이션 레이어와 API 통신, 도구 실행, 터미널 렌더링, 보안을 처리하는 Rust 성능 레이어로 구성됩니다. 이 분리는 고수준 에이전트 로직을 표현적이고 수정하기 쉽게 유지하면서, 지연 시간에 민감한 작업을 컴파일된 메모리 안전 코드로 이동시킵니다.

최상위 수준에서, 모든 사용자 상호작용은 세 단계를 거칩니다: 부트스트랩 (환경 탐색, 설정 로딩, 모드 라우팅), 쿼리 엔진 실행 (도구 호출 및 메시지 압축을 포함한 턴 루프), 응답 렌더링 (터미널에서 구문 강조가 포함된 스트리밍 마크다운). 각 단계는 양 레이어의 잘 정의된 모듈로 지원됩니다.

 User Terminal (REPL / stdin)
       |
       v
 +------------------------------------------+
 |          Rust CLI Binary                  |
 |  rusty-claude-cli  (crossterm, syntect,   |
 |  pulldown_cmark, braille spinner)         |
 +------------------------------------------+
       |
       v
 +------------------------------------------+
 |         Python Orchestration Layer        |
 |  bootstrap_graph.py  (7 stages)          |
 |  runtime.py  (route_prompt, run_turn)    |
 |  query_engine.py  (max_turns=8, stream)  |
 |  commands.py  |  tools.py  |  models.py  |
 |  context.py   |  session_store.py        |
 |  transcript.py | execution_registry.py   |
 |  tool_pool.py  | parity_audit.py         |
 |  + 50 more modules                       |
 +------------------------------------------+
       |              |              |
       v              v              v
 +-----------+  +-----------+  +-----------+
 | Rust api  |  | Rust      |  | Rust      |
 | crate     |  | runtime   |  | tools     |
 | Anthropic |  | 16 modules|  | 19 specs  |
 | client,   |  | bash,file |  | JSON      |
 | SSE,OAuth |  | ops,mcp,  |  | schemas   |
 | retry     |  | oauth,    |  |           |
 |           |  | session,  |  |           |
 |           |  | prompt,   |  |           |
 |           |  | usage     |  |           |
 +-----------+  +-----------+  +-----------+
       |              |
       v              v
 +-----------+  +---------------+
 | Rust      |  | Rust          |
 | commands  |  | compat-       |
 | 15 slash  |  | harness       |
 | commands  |  | (bridge       |
 |           |  |  layer)       |
 +-----------+  +---------------+
       |
       v
   Anthropic API  (api.anthropic.com)

Python 오케스트레이션 레이어 (src/)

Python 워크스페이스에는 긴밀하게 범위가 지정된 하위 시스템으로 구성된 60개 이상의 모듈이 포함되어 있습니다. 각 모듈은 단일 책임을 가지므로, 코드베이스를 탐색하고 독립적으로 테스트하기 쉽습니다. 아래는 모든 주요 하위 시스템에 대한 상세한 분석입니다.

부트스트랩 그래프 — bootstrap_graph.py

부트스트랩 시퀀스는 모든 claw-code 세션의 진입점입니다. 7개의 순차적 단계를 거치며, 각 단계는 이전 단계의 성공적 완료에 의존합니다:

1. 프리페치 — 다른 작업이 실행되기 전에 참조 데이터를 미리 로드하고 캐시를 워밍합니다.
2. 경고 핸들러 — 서드파티 라이브러리의 노이즈가 있는 지원 중단 메시지가 사용자 터미널에 유출되지 않도록 전역 경고 필터를 연결합니다.
3. CLI 파서 — 명령줄 인수와 플래그를 파싱하여 실행 모드를 조기에 설정합니다.
4. 설정 + 명령어 병렬 로드 — 더 빠른 시작을 위해 환경 설정과 명령어 스냅샷 로딩을 동시에 실행합니다.
5. 지연 초기화 — 파싱된 CLI 상태와 로드된 설정에 의존하는 컴포넌트를 초기화합니다.
6. 모드 라우팅 — 실행을 6가지 모드 중 하나로 라우팅합니다: local, remote, ssh, teleport, direct-connect, or deep-link.
7. 쿼리 엔진 제출 루프 — 대화형 턴 루프를 위해 쿼리 엔진에 제어권을 넘깁니다.

쿼리 엔진 — query_engine.py

쿼리 엔진은 중앙 오케스트레이션 허브입니다. 사용자, LLM, 도구 시스템 간의 대화 루프를 관리합니다. 핵심 설정 값은 QueryEngineConfig 데이터클래스에 정의되어 있습니다:

• max_turns = 8 — 엔진이 중단되기 전 사용자 쿼리당 최대 LLM 왕복 횟수입니다.
• max_budget_tokens = 2000 — 단일 쿼리 세션의 토큰 예산 상한입니다.
• compact_after_turns = 12 — 이만큼의 턴이 누적된 후, 컨텍스트 윈도우 공간을 확보하기 위해 트랜스크립트가 압축됩니다.

각 턴은 TurnResult를 생성합니다, and the QueryEnginePort class exposes session management, message compaction, and streaming. The streaming interface yields six distinct event types: message_start, command_match, tool_match, permission_denial, message_delta, and message_stop. 이 이벤트 기반 설계는 터미널 렌더러가 토큰이 도착할 때마다 점진적으로 출력을 그릴 수 있게 합니다.

런타임 — runtime.py

런타임 모듈은 원시 사용자 입력과 쿼리 엔진을 연결합니다. It provides PortRuntime, which exposes two critical methods:

• route_prompt — Tokenizes user input and scores it against available commands and tools, producing RoutedMatch objects (each with a kind, name, source_hint, and score).
• bootstrap_session / run_turn_loop — Initializes a new agent session and enters the main execution loop.

명령어 — commands.py

명령어 인벤토리는 시작 시 reference_data/commands_snapshot.json에서 로드됩니다. It exposes the CommandExecution dataclass with five fields: name, source_hint, prompt, handled, and message. Four public functions provide the command API:

• load_command_snapshot() — Reads and parses the JSON snapshot file.
• get_command(name) — Returns a single command definition by name.
• find_commands(query) — Fuzzy-searches commands matching a query string.
• execute_command(cmd) — Dispatches a command for execution.

도구 — tools.py

도구 인벤토리는 명령어 시스템을 미러링하지만 도구 호출용입니다. It loads from reference_data/tools_snapshot.json and defines a ToolExecution dataclass. Key functions include:

• load_tool_snapshot() — Cached with lru_cache for zero-cost repeated access.
• build_tool_backlog() — Constructs the list of pending tool operations.
• get_tools(simple_mode) — When simple_mode is enabled, restricts the available tools to only BashTool, FileReadTool, and FileEditTool.
• filter_tools_by_permission_context() — Applies permission filtering based on the current session context.

핵심 데이터 모델 — models.py

The models.py module defines the shared data types that flow through every layer of the system:

지원 Python 모듈

핵심 하위 시스템 외에도 Python 레이어에는 수십 개의 전문 모듈이 포함되어 있습니다:

• context.py — Workspace discovery via PortContext, which locates source_root, tests_root, assets_root, archive_root, and counts Python files.
• session_store.py — JSON-based session persistence stored in the .port_sessions/ directory.
• transcript.py — In-memory conversation transcript with a compaction strategy that keeps the last 10 messages (keep_last=10).
• execution_registry.py — Unified registry exposing MirroredCommand and MirroredTool types that bridge the Python and Rust execution models.
• tool_pool.py — Filtered tool assembly via the ToolPool class, which caps visible tools at 15 to avoid overwhelming the LLM context.
• parity_audit.py — Compares the Python and TypeScript implementations: 18 root file mappings and 31 directory mappings to track porting completeness.
• cost_tracker.py — Accumulates token usage and dollar costs across turns.
• history.py — Session history storage and retrieval.
• ink.py — Markdown panel rendering for rich terminal output.
• permissions.py — Permission checks and policy enforcement.
• prefetch.py — Data prefetching for faster bootstrap.
• remote_runtime.py — Handles remote execution modes.
• direct_modes.py — Direct-connect and deep-link mode handling.
• command_graph.py — Command dependency graph resolution.
• query.py — Lower-level query construction helpers.
• deferred_init.py — Lazy initialization for heavy components.

Rust 성능 레이어 (rust/)

Rust 워크스페이스는 6-크레이트 Cargo 워크스페이스로 구성되어 있습니다. Each crate is compiled independently, enabling incremental builds and clear dependency boundaries. Together, they provide the high-performance foundation that the Python layer calls into.

api 크레이트 — Anthropic API 클라이언트

The api crate encapsulates all communication with the Anthropic API. Its AnthropicClient handles authentication, retries, and streaming:

• Retry logic — Automatically retries on HTTP status codes 408, 409, 429, 500, 502, 503, and 504.
• Authentication — The AuthSource enum supports four modes: None, ApiKey, BearerToken, and ApiKeyAndBearer.
• Streaming — Server-Sent Events via MessageStream and SseParser for real-time token delivery.
• OAuth — Full token exchange flow for enterprise authentication.

runtime 크레이트 — 16개 모듈

The runtime crate is the largest in the Rust workspace with 16 modules covering everything from bash execution to OAuth flows:

추가 런타임 모듈에는 다음이 포함됩니다:

• bash — 샌드박싱된 셸 명령어 실행.
• json — 최소 오버헤드를 위한 무의존성 JSON 파서.
• oauth — Full PKCE authorization code flow, storing credentials at ~/.claude/credentials.json.
• remote — Upstream proxy configuration with DEFAULT_REMOTE_BASE_URL and a list of 16 no-proxy hosts.
• session — MessageRole enum (System, User, Assistant, Tool) and ContentBlock variants (Text, ToolUse, ToolResult).
• sse — Incremental SSE parser for streaming API responses.
• usage — ModelPricing with per-model rates: Sonnet at $15/$75 per million tokens, Haiku at $1/$5, Opus at $15/$75. Includes format_usd for display.

tools 크레이트 — 19개 도구 사양

The tools crate defines 19 tool specifications, each with a full JSON Schema for parameter validation. These schemas are what the LLM sees when deciding which tool to call:

commands 크레이트 — 15개 슬래시 명령어

The commands crate implements the slash command system with 15 built-in commands. Each command is classified by a CommandSource enum: Builtin, InternalOnly, or FeatureGated.

rusty-claude-cli — CLI 바이너리

The rusty-claude-cli crate is the user-facing binary. It defaults to claude-sonnet-4-20250514 as the model and provides a rich terminal experience:

• REPL — Interactive read-eval-print loop with a braille spinner animation (10 frames) for loading states.
• Syntax highlighting — Powered by syntect with the base16-ocean.dark theme.
• Markdown rendering — Uses pulldown_cmark to parse and render markdown directly in the terminal.
• Raw mode line editor — Built on crossterm for cross-platform terminal input handling.

compat-harness 크레이트

The compat-harness crate serves as the compatibility bridge between the Python orchestration layer and the Rust performance layer. It ensures that data structures, function signatures, and calling conventions remain stable across the language boundary.

데이터 흐름: 프롬프트에서 응답까지

Claw Code 아키텍처를 이해한다는 것은 단일 사용자 프롬프트가 전체 시스템을 통해 어떻게 흐르는지 추적하는 것을 의미합니다:

1. The user types a prompt in the rusty-claude-cli REPL.
2. The CLI passes input to the Python layer, where runtime.py tokenizes it and calls route_prompt to determine if it matches a slash command or should go to the LLM.
3. If it is a slash command, the commands crate handles it directly. Otherwise, the query engine takes over.
4. The query engine constructs the API request — including system prompt (built by the Rust prompt module from discovered CLAUDE.md files), conversation history (managed by transcript.py), and available tools (filtered by tool_pool.py, max 15).
5. The Rust api crate sends the request to Anthropic's API with streaming enabled, yielding SSE events back through the Python layer.
6. If the LLM response includes a tool call, the Rust runtime crate executes it (bash commands, file operations, etc.), checking permissions via the PermissionPolicy.
7. Tool results feed back into the next turn. This loop continues for up to 8 turns (Python query engine) or 16 iterations (Rust conversation runtime).
8. When the conversation accumulates more than 12 turns, the transcript is compacted — the Rust compaction module preserves the 4 most recent messages and limits estimated tokens to 10,000.

세션 & 트랜스크립트 관리

Claw-code는 두 가지 상호 보완적 메커니즘을 통해 세션 상태를 유지합니다:

• session_store.py persists full session data as JSON in the .port_sessions/ directory, enabling the /resume command to restore previous conversations.
• transcript.py keeps an in-memory rolling transcript. Its compaction algorithm retains the last 10 messages (keep_last=10), discarding older content to prevent context window overflow.

On the Rust side, the session module defines the message schema with MessageRole (System, User, Assistant, Tool) and ContentBlock (Text, ToolUse, ToolResult). This shared schema ensures both layers interpret conversation history identically.

Python-TypeScript 패리티 감사

Since claw-code is a clean-room rewrite of the Claude Code architecture, the parity_audit.py module continuously tracks implementation completeness. It maintains 18 root file mappings and 31 directory mappings that map Python modules to their TypeScript counterparts, making it straightforward to identify gaps and prioritize porting work.