How maorinka/claude-rs works
1. Overall shape
- This is a Rust Cargo workspace that splits the Claude Code clone into four boundaries: claude-cli (entrypoint/orchestration), claude-core (agent, API, auth, config, permissions), claude-tools (tool implementations), and claude-tui (terminal UI).
- The architecture is intentionally layered: UI/CLI at the top, orchestration and policy in the middle, and external effects isolated in the API, auth, and tool crates.
2. Primary runtime flow
- A user starts the binary in claude-cli.
- The CLI constructs configuration, resolves authentication, and then invokes the query engine in claude-core.
- The query engine streams requests to Anthropic, receives SSE events back, accumulates assistant content, and may trigger tool calls.
- Tool calls are delegated to claude-tools, then results are fed back into the conversation loop until completion or turn limits are reached.
3. claude-cli as orchestration boundary
- claude-cli is the only executable crate.
- It parses command-line arguments, selects interactive TUI vs non-interactive mode, and wires together core services.
- Its tests suggest it validates end-to-end command behavior rather than owning business logic.
4. claude-core as the domain and integration layer
- claude-core contains the main agent logic and most cross-cutting concerns: API client, SSE handling, retries, message normalization, auth, permissions, config, context gathering, session state, and shared types.
- This crate is the architectural center of the repo: most other crates either depend on it or are invoked by it.
5. Anthropic API and streaming subsystem
- The API stack in claude-core/src/api handles request construction, Anthropic-specific proxying, SSE streaming, response normalization, retry policy, and event accumulation.
- Data flows from the query engine into the client, then back as a stream of events that are turned into structured messages and tool requests.
- The presence of sse.rs, accumulator.rs, and normalize.rs indicates that the API boundary is not a simple HTTP wrapper; it actively transforms streaming protocol data into the internal event model.
6. Agent/query engine subsystem
- claude-core/src/query contains the conversation loop, agent state, and tool execution coordination.
- The query engine is responsible for deciding when to continue the loop, when to stop, and how to incorporate tool results into subsequent turns.
- tool_executor.rs is the bridge from model-emitted tool requests to concrete tool implementations.
7. Tools as an isolated execution layer
- claude-tools packages the filesystem/shell tools: Bash, Read, Write, Edit, Grep, and Glob, plus a registry.
- This crate is the main side-effect boundary for local machine access: shell execution, file reads/writes, search, and edits.
- The registry implies tools are dynamically looked up and executed by name, rather than hardwired in the UI.
8. Permissions and safety controls
- claude-core/src/permissions enforces whether a tool/action can run under the current policy.
- The readme’s modes—bypass, default, interactive-only—suggest permissions are a first-class architectural gate between the model’s intent and local execution.
- The TUI includes a permission dialog, so user approval is part of the interactive flow, not just a backend policy.
9. Authentication and session persistence
- claude-core/src/auth supports OAuth-style Claude Code compatibility, PKCE flow, token resolution, and storage.
- The project reads from macOS Keychain-compatible storage or API keys, which means auth is abstracted away from the query engine and shared across modes.
- session.rs indicates the conversation/session identity is tracked separately from transient UI state.
10. Context assembly
- claude-core/src/context gathers environment, git state, and system prompt data.
- This is the “prompt assembly” layer that feeds the model with local repository context before each query.
- For an architecture diagram, this is a key inbound data source alongside user input and prior conversation state.
11. Shared types and event model
- claude-core/src/types defines the common message, content, event, usage, and error structures used across the workspace.
- These shared types are the contract between API streaming, query processing, UI rendering, and CLI output.
- This keeps the crates loosely coupled while still agreeing on a single conversation/event schema.
12. TUI subsystem
- claude-tui is the interactive terminal presentation layer built on ratatui and crossterm.
- It contains layout, markdown rendering, theme handling, input management, and widgets for message lists, prompt entry, spinner, and permission dialogs.
- The TUI consumes core events and renders them, but should be treated as a pure presentation boundary rather than the source of agent logic.
13. Non-interactive vs interactive modes
- The repository supports two top-level execution paths: a scripted single-prompt mode and an interactive session mode.
- Both paths reuse the same core query engine and API/tool stack; the difference is mainly the front-end that feeds prompts and displays results.
- This is an important diagram boundary because the same backend serves both human-driven and automation-driven workflows.
14. Testing structure
- Each crate has focused tests, with claude-core carrying most behavior tests for auth, config, context, SSE, retry, permissions, and query execution.
- This suggests the architecture is intentionally decomposed so behavior can be validated at the subsystem level, not only end-to-end.
15. How to draw the diagram
- Place claude-cli at the top as the launcher.
- In the middle, show claude-core as the orchestrator, with sub-boxes for auth/config/context/permissions/query/API.
- Connect claude-core to claude-tools for local tool execution and to Anthropic Messages API for remote inference/streaming.
- Show claude-tui as an alternative presentation layer that subscribes to core events and user input, parallel to non-interactive CLI output.
Main entry points: src/lib.rs claude-core · src/lib.rs claude-tui · engine.rs Query engine · main.rs claude-cli
Components 18
Workspace
Rust Cargo workspace with four crates
- claude-rs · Rust workspace for a Claude Code-style agent
- claude-cli · Entry point and runtime wiring
crates/claude-cli/src/main.rs - claude-core · Conversation engine, policy, config, auth, and API integration
crates/claude-core/src/lib.rs - claude-tui · Interactive terminal presentation layer
crates/claude-tui/src/lib.rs - claude-tools · Local filesystem and shell tools
crates/claude-tools/src/lib.rs - Query engine · Drives turns, tool calls, and completion
crates/claude-core/src/query/engine.rs - API client · Builds requests, streams SSE, normalizes responses
crates/claude-core/src/api/client.rs - Auth · Token resolution, PKCE flow, and credential storage
crates/claude-core/src/auth/mod.rs - Config · Paths and runtime settings resolution
crates/claude-core/src/config/mod.rs - Context · Environment, git, and system prompt inputs
crates/claude-core/src/context/mod.rs - Permissions · Evaluates whether actions or tools may run
crates/claude-core/src/permissions/mod.rs - Session · Tracks session identity and durable conversation state
crates/claude-core/src/session.rs - Shared types · Common messages, events, content, usage, and errors
crates/claude-core/src/types/mod.rs - Tool executor · Maps model tool requests to concrete tool implementations
crates/claude-core/src/query/tool_executor.rs - Tool registry · Resolves tools by name
crates/claude-tools/src/registry.rs - Shell tools · Bash execution and file/search/edit operations
crates/claude-tools/src/bash.rs
Other components
- User · Interactive or scripted prompt source
- Anthropic API · Remote model inference and streaming endpoint
Connections 26
- claude-rs → claude-cli: contains · Workspace exposes the executable crate
- claude-rs → claude-core: contains · Workspace hosts the agent core
- claude-rs → claude-tui: contains · Workspace hosts the terminal UI crate
- claude-rs → claude-tools: contains · Workspace hosts local tools
- claude-cli → claude-core: wires · CLI constructs services and invokes core logic
- claude-cli → claude-tui: selects · Chooses interactive terminal mode when needed
- User → claude-cli: prompt · User starts scripted or interactive execution
- User → claude-tui: input · Interactive mode receives keyboard input
- claude-tui → claude-core: events · Renders core output and submits user actions
- claude-core → Config: loads · Resolves paths and runtime settings
- claude-core → Auth: authenticates · Resolves credentials before API use
- claude-core → Context: assembles · Builds prompt context from environment and git state
- claude-core → Session: tracks · Maintains session and conversation identity
- claude-core → Permissions: gates · Checks policy before tool execution
- claude-core → Query engine: drives · Runs the agent conversation loop
- Query engine → API client: requests · Sends model turns and receives streamed events
- API client → Anthropic API: stream · Calls the remote inference and SSE endpoint
- API client → Shared types: emits · Normalizes responses into shared events and messages
- Query engine → Tool executor: delegates · Routes model tool calls to execution
- Tool executor → Permissions: checks · Verifies tool action is allowed
- Tool executor → Tool registry: resolves · Looks up concrete tool implementations
- Tool registry → Shell tools: provides · Registry exposes filesystem and shell tools
- Shell tools → claude-core: results · Tool outputs feed back into the conversation loop
- Shell tools → User: effects · Performs local machine changes and reads
- Query engine → Shared types: consumes · Uses shared message and event schema
- claude-tui → Shared types: consumes · Renders shared messages, events, and usage data