# whatevertogo/astrcodey architecture

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

- Interactive diagram: https://gitdiagram.com/whatevertogo/astrcodey
- Repository: https://github.com/whatevertogo/astrcodey

## Overview

AstrCode is a Rust-native AI coding agent with CLI, web, desktop, and protocol interfaces. A user submits a prompt through an interface; the server manages a session and schedules an agent turn, which builds context, calls a configured model, and executes tools before streaming results back. The repository also includes persistent sessions, extension and MCP integrations, web tools, memory, and evaluation capabilities. Relationships involving unsampled subsystems are included only where the README documents the capability; source-level wiring is cited where visible.

Main entry points: [`crates/astrcode-session/src/session_runtime_services.rs`](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-session/src/session_runtime_services.rs) (Session Runtime), [`crates/astrcode-cli/src/tui/app.rs`](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/app.rs) (Terminal UI), [`crates/astrcode-server/src/session_manager.rs`](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/session_manager.rs) (Session Management), [`crates/astrcode-extensions/src/host_router.rs`](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extensions/src/host_router.rs) (Extension Host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI Entry<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[app.rs]"]
  node_tui_events["UI Event Handling<br/>[handle_event.rs]"]
  node_tui_keys["Keyboard Commands<br/>[keybinding.rs]"]
  node_cli_transport["CLI Transport<br/>[transport.rs]"]
  node_web["Web Interface<br/>[App.tsx]"]
  node_stream_ui["Stream Rendering<br/>[controller.rs]"]
end

subgraph group_server["Server and Sessions"]
  node_http["HTTP/SSE API<br/>[server.rs]"]
  node_session_manager["Session Management<br/>[session_manager.rs]"]
  node_event_bus["Server Event Bus"]
  node_scheduler["Turn Scheduler<br/>[turn_scheduler.rs]"]
  node_child_sessions["Child Sessions<br/>[child_session.rs]"]
end

subgraph group_agent["Agent Runtime"]
  node_session_runtime["Session Runtime"]
  node_tool_exec["Tool Execution<br/>[tool.rs]"]
  node_context["Prompt and Context<br/>[prompt_engine.rs]"]
  node_compaction["Context Compaction<br/>[pipeline.rs]"]
  node_eval["Evaluation Framework<br/>[runner.rs]"]
end

subgraph group_integrations["Extensions and Providers"]
  node_ai["LLM Providers<br/>[llm.rs]"]
  node_extension_host["Extension Host<br/>[host_router.rs]"]
  node_mcp["MCP Integration<br/>[http_client.rs]"]
  node_memory["Memory Extension<br/>[pipeline.rs]"]
  node_web_tools["Web Tools<br/>[lib.rs]"]
end

subgraph group_state["Persistence"]
  node_storage[("Session Storage<br/>[store.rs]")]
end

node_user(("User"))

node_user -->|"starts agent"| node_cli
node_cli -->|"opens TUI"| node_tui
node_tui -->|"handles keys"| node_tui_keys
node_tui_keys -.->|"dispatches input"| node_tui_events
node_tui -->|"applies updates"| node_tui_events
node_tui -->|"sends commands"| node_cli_transport
node_user -->|"uses web app"| node_web
node_web -->|"connects via API"| node_http
node_cli -->|"starts server"| node_http
node_http -->|"serves requests"| node_session_manager
node_session_manager -->|"schedules turns"| node_scheduler
node_session_manager -->|"publishes events"| node_event_bus
node_session_manager -->|"manages children"| node_child_sessions
node_scheduler -.->|"runs agent turn"| node_session_runtime
node_session_runtime -.->|"builds prompt"| node_context
node_session_runtime -.->|"requests completion"| node_ai
node_session_runtime -.->|"executes tools"| node_tool_exec
node_session_runtime -.->|"compacts context"| node_compaction
node_session_runtime -.->|"persists session"| node_storage
node_event_bus -.->|"streams updates"| node_cli_transport
node_cli_transport -.->|"delivers deltas"| node_stream_ui
node_session_runtime -.->|"invokes extensions"| node_extension_host
node_extension_host -.->|"routes MCP tools"| node_mcp
node_extension_host -.->|"hosts memory"| node_memory
node_extension_host -.->|"hosts web tools"| node_web_tools
node_user -->|"runs benchmarks"| node_eval

click node_cli "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/main.rs"
click node_tui "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/app.rs"
click node_tui_events "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/app/handle_event.rs"
click node_tui_keys "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/keybinding.rs"
click node_cli_transport "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/transport.rs"
click node_web "https://github.com/whatevertogo/astrcodey/blob/main/frontend/src/App.tsx"
click node_stream_ui "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/streaming/controller.rs"
click node_http "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/http/server.rs"
click node_session_manager "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/session_manager.rs"
click node_event_bus "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/server_event_bus.rs"
click node_scheduler "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/turn_scheduler.rs"
click node_child_sessions "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/child_session.rs"
click node_session_runtime "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-session/src/session_runtime_services.rs"
click node_tool_exec "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-core/src/tool.rs"
click node_context "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-context/src/prompt_engine.rs"
click node_compaction "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-session/src/compaction/pipeline.rs"
click node_ai "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-core/src/llm.rs"
click node_extension_host "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extensions/src/host_router.rs"
click node_mcp "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extension-mcp/src/http_client.rs"
click node_memory "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extension-memory/src/pipeline.rs"
click node_web_tools "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extension-web-tools/src/lib.rs"
click node_storage "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-storage/src/session_repo/store.rs"
click node_eval "https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-eval/src/runner.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_cli,node_tui,node_tui_events,node_tui_keys,node_cli_transport,node_web,node_stream_ui,node_user toneBlue
class node_http,node_session_manager,node_event_bus,node_scheduler,node_child_sessions toneAmber
class node_session_runtime,node_tool_exec,node_context,node_compaction,node_eval toneMint
class node_ai,node_extension_host,node_mcp,node_memory,node_web_tools toneRose
class node_storage toneIndigo
```

## Components

### User Interfaces

- [CLI Entry](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/main.rs): `crates/astrcode-cli/src/main.rs`
- [Terminal UI](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/app.rs): `crates/astrcode-cli/src/tui/app.rs`
- [UI Event Handling](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/app/handle_event.rs): `crates/astrcode-cli/src/tui/app/handle_event.rs`
- [Keyboard Commands](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/keybinding.rs): `crates/astrcode-cli/src/tui/keybinding.rs`
- [CLI Transport](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/transport.rs): `crates/astrcode-cli/src/transport.rs`
- [Web Interface](https://github.com/whatevertogo/astrcodey/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Stream Rendering](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-cli/src/tui/streaming/controller.rs): `crates/astrcode-cli/src/tui/streaming/controller.rs`

### Server and Sessions

- [HTTP/SSE API](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/http/server.rs): `crates/astrcode-server/src/http/server.rs`
- [Session Management](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/session_manager.rs): `crates/astrcode-server/src/session_manager.rs`
- [Server Event Bus](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/server_event_bus.rs): `crates/astrcode-server/src/server_event_bus.rs`
- [Turn Scheduler](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/turn_scheduler.rs): `crates/astrcode-server/src/turn_scheduler.rs`
- [Child Sessions](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-server/src/child_session.rs): `crates/astrcode-server/src/child_session.rs`

### Agent Runtime

- [Session Runtime](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-session/src/session_runtime_services.rs): `crates/astrcode-session/src/session_runtime_services.rs`
- [Tool Execution](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-core/src/tool.rs): `crates/astrcode-core/src/tool.rs`
- [Prompt and Context](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-context/src/prompt_engine.rs): `crates/astrcode-context/src/prompt_engine.rs`
- [Context Compaction](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-session/src/compaction/pipeline.rs): `crates/astrcode-session/src/compaction/pipeline.rs`
- [Evaluation Framework](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-eval/src/runner.rs): `crates/astrcode-eval/src/runner.rs`

### Extensions and Providers

- [LLM Providers](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-core/src/llm.rs): `crates/astrcode-core/src/llm.rs`
- [Extension Host](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extensions/src/host_router.rs): `crates/astrcode-extensions/src/host_router.rs`
- [MCP Integration](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extension-mcp/src/http_client.rs): `crates/astrcode-extension-mcp/src/http_client.rs`
- [Memory Extension](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extension-memory/src/pipeline.rs): `crates/astrcode-extension-memory/src/pipeline.rs`
- [Web Tools](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-extension-web-tools/src/lib.rs): `crates/astrcode-extension-web-tools/src/lib.rs`

### Persistence

- [Session Storage](https://github.com/whatevertogo/astrcodey/blob/main/crates/astrcode-storage/src/session_repo/store.rs): `crates/astrcode-storage/src/session_repo/store.rs`

### Other components

- **User**

## Connections

- User → CLI Entry: starts agent (evidence: `README.md`)
- CLI Entry → Terminal UI: opens TUI (evidence: `crates/astrcode-cli/src/main.rs`)
- Terminal UI → Keyboard Commands: handles keys (evidence: `crates/astrcode-cli/src/tui/mod.rs`)
- Keyboard Commands → UI Event Handling: dispatches input (evidence: `crates/astrcode-cli/src/tui/app/handle_event.rs`)
- Terminal UI → UI Event Handling: applies updates (evidence: `crates/astrcode-cli/src/tui/app.rs`)
- Terminal UI → CLI Transport: sends commands (evidence: `crates/astrcode-cli/src/tui/mod.rs`)
- User → Web Interface: uses web app (evidence: `README.md`)
- Web Interface → HTTP/SSE API: connects via API (evidence: `README.md`)
- CLI Entry → HTTP/SSE API: starts server (evidence: `crates/astrcode-cli/src/main.rs`)
- HTTP/SSE API → Session Management: serves requests (evidence: `crates/astrcode-server/src/http/server.rs`)
- Session Management → Turn Scheduler: schedules turns (evidence: `crates/astrcode-server/src/session_manager.rs`)
- Session Management → Server Event Bus: publishes events (evidence: `crates/astrcode-server/src/session_manager.rs`)
- Session Management → Child Sessions: manages children (evidence: `crates/astrcode-server/src/session_manager.rs`)
- Turn Scheduler → Session Runtime: runs agent turn
- Session Runtime → Prompt and Context: builds prompt
- Session Runtime → LLM Providers: requests completion (evidence: `README.md`)
- Session Runtime → Tool Execution: executes tools (evidence: `README.md`)
- Session Runtime → Context Compaction: compacts context (evidence: `README.md`)
- Session Runtime → Session Storage: persists session (evidence: `README.md`)
- Server Event Bus → CLI Transport: streams updates
- CLI Transport → Stream Rendering: delivers deltas
- Session Runtime → Extension Host: invokes extensions (evidence: `README.md`)
- Extension Host → MCP Integration: routes MCP tools (evidence: `README.md`)
- Extension Host → Memory Extension: hosts memory (evidence: `README.md`)
- Extension Host → Web Tools: hosts web tools (evidence: `README.md`)
- User → Evaluation Framework: runs benchmarks (evidence: `README.md`)
