Architecture Overview

Clawdius is a Rust monorepo with multiple crates, organized around a zero-trust security model and a 24-phase R&D lifecycle engine.

Monorepo Structure

clawdius/
├── crates/
│   ├── clawdius/              # CLI binary
│   ├── clawdius-core/         # Core library
│   ├── clawdius-code/         # VSCode extension helper
│   ├── clawdius-gateway/      # HTTP gateway
│   └── clawdius-mcp/          # Model Context Protocol
├── editors/vscode/            # VSCode extension (TypeScript)
├── .docs/                     # Internal documentation
└── Cargo.toml                 # Workspace root

Crate Responsibilities

Dependency Graph

clawdius (CLI) ──────────┐
                         ├──> clawdius-core
clawdius-code (VSCode) ──┘         │
                                  (external deps)
clawdius-gateway ──────────────────┘

clawdius-core is the single shared library. All binaries depend on it, and it depends only on external crates.

System Architecture

┌───────────────────────────────────────────────────────────┐
│                       Clawdius CLI                        │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐  │
│  │ Session Mgr │ │ Context     │ │ Timeline           │  │
│  │             │ │ Builder     │ │ & Checkpoints      │  │
│  └─────────────┘ └─────────────┘ └────────────────────┘  │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐  │
│  │ LLM         │ │ Graph-RAG   │ │ Plugin System      │  │
│  │ Providers   │ │             │ │                    │  │
│  └─────────────┘ └─────────────┘ └────────────────────┘  │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────────────┐  │
│  │ Sandbox     │ │ Tool Runner │ │ Enterprise Features │  │
│  │ Executors   │ │             │ │                    │  │
│  └─────────────┘ └─────────────┘ └────────────────────┘  │
└───────────────────────────────────────────────────────────┘

Core Design Principles

Nexus FSM

The Nexus FSM is a 24-phase state machine that enforces structured development through quality gates. Each phase must pass its quality gates before transitioning to the next.

Phases include Context Discovery, Requirements Engineering, Security Engineering, Performance Engineering, CI/CD Engineering, and more. See the sessions page for lifecycle details.

Cross-Crate Communication

CLI to Core

Direct Rust function calls:

#![allow(unused)]
fn main() {
use clawdius_core::{Config, SessionManager};

let config = Config::load_default()?;
let manager = SessionManager::new(&config)?;
}

VSCode to Core

JSON-RPC over stdio via clawdius-code:

VSCode Extension (TypeScript)
    │ JSON-RPC (stdio)
    ▼
clawdius-code Binary
    │ Direct calls
    ▼
clawdius-core Library

Performance

The release profile uses fat LTO, single codegen unit, and symbol stripping for optimal binary size and performance.

Feature Flags

Feature flags propagate across crates. Key flags: