# maorinka/claude-rs architecture

> Architecture diagram of the GitHub repository maorinka/claude-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maorinka/claude-rs
- Repository: https://github.com/maorinka/claude-rs

## Overview

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: [`crates/claude-core/src/lib.rs`](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/lib.rs) (claude-core), [`crates/claude-tui/src/lib.rs`](https://github.com/maorinka/claude-rs/blob/main/crates/claude-tui/src/lib.rs) (claude-tui), [`crates/claude-core/src/query/engine.rs`](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/query/engine.rs) (Query engine), [`crates/claude-cli/src/main.rs`](https://github.com/maorinka/claude-rs/blob/main/crates/claude-cli/src/main.rs) (claude-cli)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_repo["claude-rs<br/>workspace"]
  node_cli["claude-cli<br/>binary<br/>[main.rs]"]
  node_core["claude-core<br/>agent-core<br/>[lib.rs]"]
  node_tui["claude-tui<br/>terminal-ui<br/>[lib.rs]"]
  node_tools["claude-tools<br/>toolkit<br/>[lib.rs]"]
  node_query(("Query engine<br/>conversation-loop<br/>[engine.rs]"))
  node_api[("API client<br/>anthropic-streaming<br/>[client.rs]")]
  node_auth(("Auth<br/>[mod.rs]"))
  node_config["Config<br/>settings<br/>[mod.rs]"]
  node_context["Context<br/>prompt-assembly<br/>[mod.rs]"]
  node_permissions{{"Permissions<br/>policy-gate<br/>[mod.rs]"}}
  node_session["Session<br/>conversation-state<br/>[session.rs]"]
  node_types["Shared types<br/>event-schema<br/>[mod.rs]"]
  node_tool_exec(("Tool executor<br/>tool-bridge<br/>[tool_executor.rs]"))
  node_registry["Tool registry<br/>lookup<br/>[registry.rs]"]
  node_shell_tools[("Shell tools<br/>local-effects<br/>[bash.rs]")]
end

node_user(("User<br/>human"))
node_anthropic[("Anthropic API<br/>external-service")]

node_repo -->|"contains"| node_cli
node_repo -->|"contains"| node_core
node_repo -->|"contains"| node_tui
node_repo -->|"contains"| node_tools
node_cli -->|"wires"| node_core
node_cli -->|"selects"| node_tui
node_user -->|"prompt"| node_cli
node_user -->|"input"| node_tui
node_tui -->|"events"| node_core
node_core -->|"loads"| node_config
node_core -->|"authenticates"| node_auth
node_core -->|"assembles"| node_context
node_core -->|"tracks"| node_session
node_core -->|"gates"| node_permissions
node_core -->|"drives"| node_query
node_query -->|"requests"| node_api
node_api -->|"stream"| node_anthropic
node_api -->|"emits"| node_types
node_query -->|"delegates"| node_tool_exec
node_tool_exec -->|"checks"| node_permissions
node_tool_exec -->|"resolves"| node_registry
node_registry -->|"provides"| node_shell_tools
node_shell_tools -->|"results"| node_core
node_shell_tools -->|"effects"| node_user
node_query -->|"consumes"| node_types
node_tui -->|"consumes"| node_types

click node_cli "https://github.com/maorinka/claude-rs/blob/main/crates/claude-cli/src/main.rs"
click node_core "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/lib.rs"
click node_tui "https://github.com/maorinka/claude-rs/blob/main/crates/claude-tui/src/lib.rs"
click node_tools "https://github.com/maorinka/claude-rs/blob/main/crates/claude-tools/src/lib.rs"
click node_query "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/query/engine.rs"
click node_api "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/api/client.rs"
click node_auth "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/auth/mod.rs"
click node_config "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/config/mod.rs"
click node_context "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/context/mod.rs"
click node_permissions "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/permissions/mod.rs"
click node_session "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/session.rs"
click node_types "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/types/mod.rs"
click node_tool_exec "https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/query/tool_executor.rs"
click node_registry "https://github.com/maorinka/claude-rs/blob/main/crates/claude-tools/src/registry.rs"
click node_shell_tools "https://github.com/maorinka/claude-rs/blob/main/crates/claude-tools/src/bash.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo,node_cli,node_core,node_tui,node_tools,node_query,node_api,node_auth,node_config,node_context,node_permissions,node_session,node_types,node_tool_exec,node_registry,node_shell_tools toneBlue
class node_user,node_anthropic toneNeutral
```

## Components

### Workspace

Rust Cargo workspace with four crates

- **claude-rs**: workspace · Rust workspace for a Claude Code-style agent
- [claude-cli](https://github.com/maorinka/claude-rs/blob/main/crates/claude-cli/src/main.rs): binary · Entry point and runtime wiring · `crates/claude-cli/src/main.rs`
- [claude-core](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/lib.rs): agent-core · Conversation engine, policy, config, auth, and API integration · `crates/claude-core/src/lib.rs`
- [claude-tui](https://github.com/maorinka/claude-rs/blob/main/crates/claude-tui/src/lib.rs): terminal-ui · Interactive terminal presentation layer · `crates/claude-tui/src/lib.rs`
- [claude-tools](https://github.com/maorinka/claude-rs/blob/main/crates/claude-tools/src/lib.rs): toolkit · Local filesystem and shell tools · `crates/claude-tools/src/lib.rs`
- [Query engine](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/query/engine.rs): conversation-loop · Drives turns, tool calls, and completion · `crates/claude-core/src/query/engine.rs`
- [API client](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/api/client.rs): anthropic-streaming · Builds requests, streams SSE, normalizes responses · `crates/claude-core/src/api/client.rs`
- [Auth](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/auth/mod.rs): oauth-storage · Token resolution, PKCE flow, and credential storage · `crates/claude-core/src/auth/mod.rs`
- [Config](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/config/mod.rs): settings · Paths and runtime settings resolution · `crates/claude-core/src/config/mod.rs`
- [Context](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/context/mod.rs): prompt-assembly · Environment, git, and system prompt inputs · `crates/claude-core/src/context/mod.rs`
- [Permissions](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/permissions/mod.rs): policy-gate · Evaluates whether actions or tools may run · `crates/claude-core/src/permissions/mod.rs`
- [Session](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/session.rs): conversation-state · Tracks session identity and durable conversation state · `crates/claude-core/src/session.rs`
- [Shared types](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/types/mod.rs): event-schema · Common messages, events, content, usage, and errors · `crates/claude-core/src/types/mod.rs`
- [Tool executor](https://github.com/maorinka/claude-rs/blob/main/crates/claude-core/src/query/tool_executor.rs): tool-bridge · Maps model tool requests to concrete tool implementations · `crates/claude-core/src/query/tool_executor.rs`
- [Tool registry](https://github.com/maorinka/claude-rs/blob/main/crates/claude-tools/src/registry.rs): lookup · Resolves tools by name · `crates/claude-tools/src/registry.rs`
- [Shell tools](https://github.com/maorinka/claude-rs/blob/main/crates/claude-tools/src/bash.rs): local-effects · Bash execution and file/search/edit operations · `crates/claude-tools/src/bash.rs`

### Other components

- **User**: human · Interactive or scripted prompt source
- **Anthropic API**: external-service · Remote model inference and streaming endpoint

## Connections

- 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
