How kuberwastaken/claurst works
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/lib.rs Tools · src/lib.rs Query · src/lib.rs Core · coordinator.rs Coordinator
Components 28
Entry & UI
User-facing launch and terminal interaction layers
- CLI · Main executable entrypoint; starts the app and auth flow
src-rust/crates/cli/src/main.rs - TUI · Interactive terminal presentation and input layer
src-rust/crates/tui/src/lib.rs - App state · Top-level terminal app state and lifecycle
src-rust/crates/tui/src/app.rs - Render · Terminal rendering and screen composition
src-rust/crates/tui/src/render.rs - Input · Keyboard and interaction handling
src-rust/crates/tui/src/input.rs - Bridge view · 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 · Named command routing and structured actions
src-rust/crates/commands/src/lib.rs - Query · Central coordination loop for sessions and reasoning
src-rust/crates/query/src/lib.rs - Coordinator · Orchestrates agent steps and long-running conversation flow
src-rust/crates/query/src/coordinator.rs - Compact · Compaction and context reduction for long sessions
src-rust/crates/query/src/compact.rs - Scheduler · 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 · Main execution surface for agent actions
src-rust/crates/tools/src/lib.rs - File ops · Read, write, edit, and search file-oriented actions
src-rust/crates/tools/src/file_read.rs - Shell ops · Bash and PowerShell execution capabilities
src-rust/crates/tools/src/bash.rs - Web ops · Search and fetch access to external web content
src-rust/crates/tools/src/web_search.rs - Task ops · Background work, todos, sleep, and message-sending primitives
src-rust/crates/tools/src/tasks.rs - MCP resources · Tool-side access to Model Context Protocol resources
src-rust/crates/tools/src/mcp_resources.rs - Plugins · Plugin loading, manifests, registry, and hooks
src-rust/crates/plugins/src/lib.rs - Buddy · Feature-gated companion subsystem
src-rust/crates/buddy/src/lib.rs
Shared Core
Cross-cutting runtime services and shared infrastructure
- Core · Cross-cutting infrastructure used across crates
src-rust/crates/core/src/lib.rs - System prompt · Builds and stores model-facing prompt content
src-rust/crates/core/src/system_prompt.rs - OAuth config · Shared OAuth configuration and credentials plumbing
src-rust/crates/core/src/oauth_config.rs - Memory dir · Workspace and memory-directory handling
src-rust/crates/core/src/memdir.rs - Analytics · Usage and event tracking infrastructure
src-rust/crates/core/src/analytics.rs
Integrations
External protocol and remote-session boundaries
Design Docs
Repository architecture reference material
- Spec docs · Architecture and behavior documentation, not runtime code
spec/INDEX.md
Connections 35
- 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