# kuberwastaken/claurst architecture

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

- Interactive diagram: https://gitdiagram.com/kuberwastaken/claurst
- Repository: https://github.com/kuberwastaken/claurst

## Overview

1. **Repo shape**
   - This is a Rust workspace in `src-rust/`, with a clean separation between a small set of runtime crates and a large `spec/` directory that documents behavior and architecture.
   - The `spec/` files are design documentation, not the runtime system. The executable behavior lives under `src-rust/crates/*`.

2. **Top-level runtime entrypoint**
   - The primary user-facing binary is `crates/cli`.
   - `cli/src/main.rs` is the entry boundary for launching the app, and `oauth_flow.rs` indicates the CLI can initiate authentication before normal operation.
   - `system_prompt.txt` suggests the CLI also bootstraps model-facing prompt content.

3. **Interactive terminal layer**
   - `crates/tui` is the terminal UI subsystem.
   - It is split into app state, input handling, rendering, dialogs, overlays, notifications, settings/theme/privacy screens, and bridge state.
   - This crate is the presentation boundary between the user and the agent/runtime state.

4. **Agent orchestration and reasoning loop**
   - `crates/query` is the core orchestration layer that coordinates agent behavior over time.
   - Its modules (`coordinator`, `compact`, `cron_scheduler`, `auto_dream`, `agent_tool`) suggest it manages long-running sessions, multi-step reasoning, compaction/summarization, scheduled activity, and delegation.
   - In an architecture diagram, this is the central controller between the UI, tools, and external services.

5. **Tool execution subsystem**
   - `crates/tools` is the main capability surface exposed to the agent.
   - It contains file operations, shell execution, search, web access, task/background work, notebook editing, MCP access, worktree control, cron, user interaction, and message-sending primitives.
   - Most of the app’s “real work” flows through this crate: the query/orchestrator asks for actions, and tools perform them.

6. **Core shared services**
   - `crates/core` holds common infrastructure used by multiple subsystems.
   - The file names show cross-cutting concerns such as analytics, keybindings, LSP integration, memory directory handling, migrations, OAuth config, output styling, system prompt assembly, team memory sync, and voice support.
   - This crate is the shared foundation, not a user-facing layer.

7. **Commands and named actions**
   - `crates/commands` appears to define the command registry and named command routing.
   - This is likely the boundary for slash-commands or structured CLI commands that trigger workflows beyond normal chat/tool use.
   - It sits between the terminal/UI and the orchestration layer.

8. **Plugins and hooks**
   - `crates/plugins` provides extension loading, manifests, plugin definitions, registry, and hook execution.
   - Architecturally, this is an optional extension boundary that lets external or user-defined logic participate in app events.
   - It likely feeds into the tool/orchestration system rather than replacing it.

9. **Remote/bridge integration**
   - `crates/bridge` handles remote-session or cloud-side coordination.
   - The presence of a separate bridge crate implies a boundary between local CLI/TUI state and a remote control or relay service.
   - This is important for diagramming because it is not just another tool; it is an integration layer with its own authentication/session semantics.

10. **External protocol integrations**
   - `crates/mcp` is the Model Context Protocol integration boundary.
   - `crates/api` is the outbound service/API layer, likely responsible for model requests, auth headers, feature negotiation, and billing/telemetry-adjacent metadata.
   - These are the main exits from the local app into external systems.

11. **Optional/feature-gated subsystems**
   - `crates/buddy` is a separate feature area for a companion/pet-like UI/system.
   - The repository structure and README indicate there are compile-time and runtime feature gates throughout the workspace; some capabilities are not always present in every build.
   - For an architecture diagram, treat these as optional branches hanging off the core orchestration layer.

12. **How data flows through the system**
   - Typical flow is: CLI starts → TUI renders and collects input → query/orchestrator interprets intent → tools execute actions or external API calls → results return to query → TUI updates the user.
   - Cross-cutting services in `core` support many of these steps, while `plugins`, `bridge`, and `mcp` extend the system at the edges.
   - The `spec/` directory is best drawn as the design reference that informed these implementations, not as a runtime dependency.

13. **Practical diagram boundaries**
   - Good hard boundaries for a diagram are: **user interaction**, **orchestration**, **tool execution**, **shared services**, **external APIs/protocols**, and **optional extensions**.
   - The clearest “center” of the architecture is `query`, with `tui` on one side and `tools/api/bridge/mcp` on the other.

Main entry points: [`src-rust/crates/tools/src/lib.rs`](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/lib.rs) (Tools), [`src-rust/crates/query/src/lib.rs`](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/lib.rs) (Query), [`src-rust/crates/core/src/lib.rs`](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/lib.rs) (Core), [`src-rust/crates/query/src/coordinator.rs`](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/coordinator.rs) (Coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entry & UI"]
  node_n_cli["CLI<br/>binary entry<br/>[main.rs]"]
  node_n_tui["TUI<br/>terminal UI<br/>[lib.rs]"]
  node_n_tui_app["App state<br/>ui state<br/>[app.rs]"]
  node_n_tui_render["Render<br/>[render.rs]"]
  node_n_tui_input["Input<br/>[input.rs]"]
  node_n_tui_bridge["Bridge view<br/>ui bridge state<br/>[bridge_state.rs]"]
end

subgraph group_grp_control["Control Flow"]
  node_n_commands["Commands<br/>command registry<br/>[lib.rs]"]
  node_n_query{{"Query<br/>agent orchestrator<br/>[lib.rs]"}}
  node_n_query_coord["Coordinator<br/>session control<br/>[coordinator.rs]"]
  node_n_query_compact["Compact<br/>summarization<br/>[compact.rs]"]
  node_n_query_sched["Scheduler<br/>cron loop<br/>[cron_scheduler.rs]"]
end

subgraph group_grp_capabilities["Capabilities"]
  node_n_tools["Tools<br/>capability surface<br/>[lib.rs]"]
  node_n_tools_fs["File ops<br/>filesystem tools<br/>[file_read.rs]"]
  node_n_tools_shell["Shell ops<br/>command tools<br/>[bash.rs]"]
  node_n_tools_web["Web ops<br/>network tools<br/>[web_search.rs]"]
  node_n_tools_task["Task ops<br/>workflow tools<br/>[tasks.rs]"]
  node_n_tools_mcp["MCP resources<br/>protocol tools<br/>[mcp_resources.rs]"]
  node_n_plugins["Plugins<br/>extension system<br/>[lib.rs]"]
  node_n_buddy["Buddy<br/>optional feature<br/>[lib.rs]"]
end

subgraph group_grp_shared["Shared Core"]
  node_n_core[("Core<br/>shared services<br/>[lib.rs]")]
  node_n_core_prompt["System prompt<br/>prompt assembly<br/>[system_prompt.rs]"]
  node_n_core_oauth["OAuth config<br/>[oauth_config.rs]"]
  node_n_core_mem["Memory dir<br/>state storage<br/>[memdir.rs]"]
  node_n_core_analytics["Analytics<br/>telemetry<br/>[analytics.rs]"]
end

subgraph group_grp_integrations["Integrations"]
  node_n_api["API<br/>external service client<br/>[lib.rs]"]
  node_n_bridge["Bridge<br/>remote session<br/>[lib.rs]"]
  node_n_mcp["MCP<br/>protocol gateway<br/>[lib.rs]"]
end

subgraph group_grp_docs["Design Docs"]
  node_n_spec["Spec docs<br/>design reference<br/>[INDEX.md]"]
end

node_n_cli -->|"launches"| node_n_tui
node_n_cli -->|"auth setup"| node_n_core_oauth
node_n_cli -->|"loads prompt"| node_n_core_prompt
node_n_tui -->|"owns"| node_n_tui_app
node_n_tui_app -->|"handles"| node_n_tui_input
node_n_tui_app -->|"renders"| node_n_tui_render
node_n_tui_app -->|"shows"| node_n_tui_bridge
node_n_tui -->|"invokes"| node_n_commands
node_n_commands -->|"dispatches"| node_n_query
node_n_tui -->|"submits intent"| node_n_query
node_n_query -->|"coordinates"| node_n_query_coord
node_n_query -->|"compacts"| node_n_query_compact
node_n_query -->|"schedules"| node_n_query_sched
node_n_query_coord -->|"requests work"| node_n_tools
node_n_query_coord -->|"calls"| node_n_api
node_n_query_coord -->|"extends with"| node_n_plugins
node_n_query_coord -->|"relays"| node_n_bridge
node_n_tools -->|"includes"| node_n_tools_fs
node_n_tools -->|"includes"| node_n_tools_shell
node_n_tools -->|"includes"| node_n_tools_web
node_n_tools -->|"includes"| node_n_tools_task
node_n_tools -->|"includes"| node_n_tools_mcp
node_n_tools -->|"integrates"| node_n_mcp
node_n_plugins -->|"hooks into"| node_n_tools
node_n_core -->|"supports"| node_n_query
node_n_core -->|"supports"| node_n_tui
node_n_core -->|"supports"| node_n_tools
node_n_core -->|"supports"| node_n_api
node_n_core -->|"supports"| node_n_bridge
node_n_core -->|"supports"| node_n_buddy
node_n_api -->|"uses auth"| node_n_core_oauth
node_n_bridge -->|"exposes state"| node_n_tui_bridge
node_n_spec -.->|"documents"| node_n_query
node_n_spec -.->|"documents"| node_n_tools
node_n_spec -.->|"documents"| node_n_bridge

click node_n_cli "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/cli/src/main.rs"
click node_n_tui "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/lib.rs"
click node_n_tui_app "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/app.rs"
click node_n_tui_render "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/render.rs"
click node_n_tui_input "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/input.rs"
click node_n_tui_bridge "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/bridge_state.rs"
click node_n_commands "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/commands/src/lib.rs"
click node_n_query "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/lib.rs"
click node_n_query_coord "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/coordinator.rs"
click node_n_query_compact "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/compact.rs"
click node_n_query_sched "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/cron_scheduler.rs"
click node_n_tools "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/lib.rs"
click node_n_tools_fs "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/file_read.rs"
click node_n_tools_shell "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/bash.rs"
click node_n_tools_web "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/web_search.rs"
click node_n_tools_task "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/tasks.rs"
click node_n_tools_mcp "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/mcp_resources.rs"
click node_n_plugins "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/plugins/src/lib.rs"
click node_n_buddy "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/buddy/src/lib.rs"
click node_n_core "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/lib.rs"
click node_n_core_prompt "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/system_prompt.rs"
click node_n_core_oauth "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/oauth_config.rs"
click node_n_core_mem "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/memdir.rs"
click node_n_core_analytics "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/analytics.rs"
click node_n_api "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/api/src/lib.rs"
click node_n_bridge "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/bridge/src/lib.rs"
click node_n_mcp "https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/mcp/src/lib.rs"
click node_n_spec "https://github.com/kuberwastaken/claurst/blob/main/spec/INDEX.md"

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_n_cli,node_n_tui,node_n_tui_app,node_n_tui_render,node_n_tui_input,node_n_tui_bridge toneBlue
class node_n_commands,node_n_query,node_n_query_coord,node_n_query_compact,node_n_query_sched toneAmber
class node_n_tools,node_n_tools_fs,node_n_tools_shell,node_n_tools_web,node_n_tools_task,node_n_tools_mcp,node_n_plugins,node_n_buddy toneMint
class node_n_core,node_n_core_prompt,node_n_core_oauth,node_n_core_mem,node_n_core_analytics toneRose
class node_n_api,node_n_bridge,node_n_mcp toneIndigo
class node_n_spec toneTeal
```

## Components

### Entry & UI

User-facing launch and terminal interaction layers

- [CLI](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/cli/src/main.rs): binary entry · Main executable entrypoint; starts the app and auth flow · `src-rust/crates/cli/src/main.rs`
- [TUI](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/lib.rs): terminal UI · Interactive terminal presentation and input layer · `src-rust/crates/tui/src/lib.rs`
- [App state](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/app.rs): ui state · Top-level terminal app state and lifecycle · `src-rust/crates/tui/src/app.rs`
- [Render](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/render.rs): ui render · Terminal rendering and screen composition · `src-rust/crates/tui/src/render.rs`
- [Input](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/input.rs): ui input · Keyboard and interaction handling · `src-rust/crates/tui/src/input.rs`
- [Bridge view](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tui/src/bridge_state.rs): ui bridge state · UI-facing state for remote/bridge coordination · `src-rust/crates/tui/src/bridge_state.rs`

### Control Flow

Command routing and long-running agent orchestration

- [Commands](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/commands/src/lib.rs): command registry · Named command routing and structured actions · `src-rust/crates/commands/src/lib.rs`
- [Query](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/lib.rs): agent orchestrator · Central coordination loop for sessions and reasoning · `src-rust/crates/query/src/lib.rs`
- [Coordinator](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/coordinator.rs): session control · Orchestrates agent steps and long-running conversation flow · `src-rust/crates/query/src/coordinator.rs`
- [Compact](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/compact.rs): summarization · Compaction and context reduction for long sessions · `src-rust/crates/query/src/compact.rs`
- [Scheduler](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/query/src/cron_scheduler.rs): cron loop · Scheduled and deferred activity orchestration · `src-rust/crates/query/src/cron_scheduler.rs`

### Capabilities

Tool execution surface and feature subsystems used by the agent

- [Tools](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/lib.rs): capability surface · Main execution surface for agent actions · `src-rust/crates/tools/src/lib.rs`
- [File ops](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/file_read.rs): filesystem tools · Read, write, edit, and search file-oriented actions · `src-rust/crates/tools/src/file_read.rs`
- [Shell ops](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/bash.rs): command tools · Bash and PowerShell execution capabilities · `src-rust/crates/tools/src/bash.rs`
- [Web ops](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/web_search.rs): network tools · Search and fetch access to external web content · `src-rust/crates/tools/src/web_search.rs`
- [Task ops](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/tasks.rs): workflow tools · Background work, todos, sleep, and message-sending primitives · `src-rust/crates/tools/src/tasks.rs`
- [MCP resources](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/tools/src/mcp_resources.rs): protocol tools · Tool-side access to Model Context Protocol resources · `src-rust/crates/tools/src/mcp_resources.rs`
- [Plugins](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/plugins/src/lib.rs): extension system · Plugin loading, manifests, registry, and hooks · `src-rust/crates/plugins/src/lib.rs`
- [Buddy](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/buddy/src/lib.rs): optional feature · Feature-gated companion subsystem · `src-rust/crates/buddy/src/lib.rs`

### Shared Core

Cross-cutting runtime services and shared infrastructure

- [Core](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/lib.rs): shared services · Cross-cutting infrastructure used across crates · `src-rust/crates/core/src/lib.rs`
- [System prompt](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/system_prompt.rs): prompt assembly · Builds and stores model-facing prompt content · `src-rust/crates/core/src/system_prompt.rs`
- [OAuth config](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/oauth_config.rs): auth config · Shared OAuth configuration and credentials plumbing · `src-rust/crates/core/src/oauth_config.rs`
- [Memory dir](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/memdir.rs): state storage · Workspace and memory-directory handling · `src-rust/crates/core/src/memdir.rs`
- [Analytics](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/core/src/analytics.rs): telemetry · Usage and event tracking infrastructure · `src-rust/crates/core/src/analytics.rs`

### Integrations

External protocol and remote-session boundaries

- [API](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/api/src/lib.rs): external service client · Outbound service layer for model and account-facing APIs · `src-rust/crates/api/src/lib.rs`
- [Bridge](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/bridge/src/lib.rs): remote session · Remote relay and local-to-cloud coordination boundary · `src-rust/crates/bridge/src/lib.rs`
- [MCP](https://github.com/kuberwastaken/claurst/blob/main/src-rust/crates/mcp/src/lib.rs): protocol gateway · Model Context Protocol integration boundary · `src-rust/crates/mcp/src/lib.rs`

### Design Docs

Repository architecture reference material

- [Spec docs](https://github.com/kuberwastaken/claurst/blob/main/spec/INDEX.md): design reference · Architecture and behavior documentation, not runtime code · `spec/INDEX.md`

## Connections

- CLI → TUI: launches · CLI starts the terminal UI for interactive use
- CLI → OAuth config: auth setup · CLI bootstraps authentication flow and config
- CLI → System prompt: loads prompt · CLI includes the model-facing system prompt text
- TUI → App state: owns · The TUI crate is centered around app state lifecycle
- App state → Input: handles · App state forwards user input into interaction handling
- App state → Render: renders · App state drives screen composition and refresh
- App state → Bridge view: shows · App state exposes bridge/remote status to the user
- TUI → Commands: invokes · Terminal actions can route into named commands
- Commands → Query: dispatches · Structured commands ultimately trigger orchestration flows
- TUI → Query: submits intent · User chat and actions are forwarded to the orchestrator
- Query → Coordinator: coordinates · Core query crate is driven by its coordinator loop
- Query → Compact: compacts · Long-running context is summarized and reduced
- Query → Scheduler: schedules · Deferred and periodic behaviors are managed here
- Coordinator → Tools: requests work · Coordinator delegates actions to the tool surface
- Coordinator → API: calls · Orchestration can invoke outbound API/model services
- Coordinator → Plugins: extends with · Plugin hooks can participate in orchestration events
- Coordinator → Bridge: relays · Remote/bridge state can be coordinated from the query loop
- Tools → File ops: includes · File-oriented primitives are a major tool family
- Tools → Shell ops: includes · Shell execution is a core capability surface
- Tools → Web ops: includes · Web search and fetch are exposed as tools
- Tools → Task ops: includes · Tasking, messaging, and timing tools support workflows
- Tools → MCP resources: includes · Tooling can access MCP resources
- Tools → MCP: integrates · The tools layer connects to the protocol gateway
- Plugins → Tools: hooks into · Plugins augment the agent capability surface via hooks
- Core → Query: supports · Shared services underpin orchestration behavior
- Core → TUI: supports · UI settings, styles, and keybindings come from core services
- Core → Tools: supports · Tool implementations reuse shared runtime infrastructure
- Core → API: supports · API clients share common auth and prompt/config plumbing
- Core → Bridge: supports · Remote coordination uses shared state and config services
- Core → Buddy: supports · Optional companion features rely on shared services
- API → OAuth config: uses auth · External requests depend on shared OAuth configuration
- Bridge → Bridge view: exposes state · Bridge state is surfaced in the terminal UI
- Spec docs → Query: documents · Design docs describe the query/orchestration architecture
- Spec docs → Tools: documents · Design docs describe the tool subsystem
- Spec docs → Bridge: documents · Design docs describe the bridge/remote boundary
