Introduction to Clawdius

Clawdius is a high-assurance AI coding assistant built in Rust. It combines the power of large language models with formal verification, secure sandboxing, and enterprise-grade features to provide a trustworthy development companion.

Why Clawdius?

🛡️ Security First

Clawdius was designed from the ground up with security as a primary concern:

• 7 Sandbox Backends: From lightweight WASM to hardware-isolated Firecracker microVMs
• 104 Formal Verification Theorems: Mathematically proven correctness for critical operations
• Enterprise SSO: SAML 2.0, OIDC, Okta, Azure AD, and GitHub integration
• Comprehensive Audit Logging: SQLite, Elasticsearch, and webhook backends

⚡ Native Performance

Built in Rust for maximum performance:

• <20ms cold boot: Faster than any competitor
• Zero-copy streaming: Efficient real-time output
• Memory-efficient: Minimal resource footprint
• Cross-platform: Linux, macOS, Windows support

🔧 Extensible Architecture

• Plugin System: WASM-based plugins with 26 hook types
• Multiple LLM Providers: Anthropic, OpenAI, Ollama, and custom endpoints
• Graph-RAG: Enhanced context through code graph analysis
• Timeline & Checkpoints: Full session history and rollback

Feature Comparison

Quick Start

# Install from crates.io
cargo install clawdius

# Run the interactive setup wizard (new in v1.2.0!)
clawdius setup

# Or manually set your API key
clawdius config set api_key YOUR_ANTHROPIC_API_KEY

# Start chatting
clawdius chat

New: Interactive Setup Wizard

Version 1.2.0 introduces an interactive setup wizard that guides you through:

• Provider Selection: Choose from Anthropic, OpenAI, Ollama (local), or Zhipu AI
• API Key Configuration: Secure storage using your system keyring
• Settings Presets: Balanced, Security-focused, Performance-optimized, or Development mode
• Ollama Connectivity Check: Automatic TCP verification for local LLMs

# First-time setup
clawdius setup

# Quick setup with pre-selected provider
clawdius setup --quick --provider anthropic

Architecture Overview

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

What's Next?

• Installation Guide - Get Clawdius running on your system
• Configuration - Customize Clawdius for your workflow
• First Chat - Your first conversation with Clawdius
• Architecture Overview - Understand how Clawdius works

Getting Help

• Documentation: docs.clawdius.dev
• GitHub: github.com/WyattAu/clawdius
• Discord: Join our community
• GitHub Discussions: For Q&A and feature requests

License

Clawdius is licensed under the MIT License.

Installation

Clawdius can be installed in several ways depending on your platform and preferences.

Quick Install

Linux and macOS

curl -fsSL https://clawdius.dev/install.sh | sh

Windows (PowerShell)

irm https://clawdius.dev/install.ps1 | iex

Package Managers

Homebrew (macOS/Linux)

brew tap clawdius/tap
brew install clawdius

Cargo (All Platforms)

cargo install clawdius

Arch Linux (AUR)

yay -S clawdius-bin
# Or build from source:
yay -S clawdius-git

Nix

# Using nixpkgs
nix-env -iA nixpkgs.clawdius

# Using flake
nix profile install github:WyattAu/clawdius

Pre-built Binaries

Download pre-built binaries from GitHub Releases:

Manual Installation

# Download and extract
curl -LO https://github.com/WyattAu/clawdius/releases/download/v1.0.0/clawdius-linux-x86_64.tar.gz
tar xzf clawdius-linux-x86_64.tar.gz

# Move to PATH
sudo mv clawdius /usr/local/bin/

# Verify installation
clawdius --version

Build from Source

Prerequisites

• Rust 1.75+ (recommended: latest stable)
• C compiler (gcc, clang, or MSVC)
• pkg-config (Linux)

Build Steps

# Clone the repository
git clone https://github.com/WyattAu/clawdius.git
cd clawdius

# Build release binary
cargo build --release

# Install locally
cargo install --path crates/clawdius

# Or copy binary manually
cp target/release/clawdius /usr/local/bin/

Build Features

Clawdius supports optional features:

# Enable all features
cargo build --release --all-features

# Enable only enterprise features
cargo build --release --features enterprise

# Minimal build (no plugins, basic sandbox)
cargo build --release --no-default-features

Docker

# Pull official image
docker pull clawdius/clawdius:latest

# Run with current directory mounted
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.config/clawdius:/root/.config/clawdius \
  clawdius/clawdius:latest chat

Docker Compose

version: '3.8'
services:
  clawdius:
    image: clawdius/clawdius:latest
    volumes:
      - ./:/workspace
      - clawdius-config:/root/.config/clawdius
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
volumes:
  clawdius-config:

Verification

After installation, verify everything works:

# Check version
clawdius --version

# Run the interactive setup wizard (recommended for first-time users)
clawdius setup

# Or run diagnostics
clawdius doctor

# Quick test (requires API key)
clawdius chat --message "Hello, Clawdius!"

First-Time Setup

New in v1.2.0: Use the interactive setup wizard to configure Clawdius:

clawdius setup

The wizard will guide you through:

1. Provider Selection - Choose your LLM provider (Anthropic, OpenAI, Ollama, Zhipu AI)
2. API Key Configuration - Enter and securely store your API key
3. Settings Preset - Choose a configuration preset:
   • Balanced: Good defaults for most users
   • Security: Maximum sandboxing and audit logging
   • Performance: Optimized for speed
   • Development: Verbose logging and debugging features

Quick Setup Options

# Skip welcome screen
clawdius setup --quick

# Pre-select provider
clawdius setup --provider anthropic
clawdius setup --provider ollama  # For local LLMs

Shell Completion

Enable shell completion for your shell:

Bash

clawdius completion bash > /etc/bash_completion.d/clawdius
# Or for user-only:
clawdius completion bash > ~/.local/share/bash-completion/completions/clawdius

Zsh

clawdius completion zsh > "${fpath[1]}/_clawdius"

Fish

clawdius completion fish > ~/.config/fish/completions/clawdius.fish

PowerShell

clawdius completion powershell | Out-String | Invoke-Expression

Next Steps

• Configuration - Set up your API keys and preferences
• First Chat - Your first conversation with Clawdius

Configuration

Clawdius is highly configurable. This guide covers the essential configuration options.

Interactive Setup (Recommended)

New in v1.2.0: Use the interactive setup wizard for first-time configuration:

clawdius setup

The wizard provides:

• Guided provider selection with descriptions
• Secure API key storage using your system keyring
• Preset configurations for common use cases
• Connectivity verification for local LLMs (Ollama)
• Quick start examples after setup completes

Setup Presets

Configuration File Location

Clawdius looks for configuration in the following locations (in order):

1. CLAWDIUS_CONFIG environment variable (if set)
2. ./.clawdius/config.toml (project-local)
3. ~/.config/clawdius/config.toml (user-level)
4. /etc/clawdius/config.toml (system-wide)

Quick Setup

Set API Key

# Using CLI
clawdius config set api_key sk-ant-xxxxx
# Or set environment variable
export ANTHROPIC_API_KEY=sk-ant-xxxxx

Set Default Provider

clawdius config set provider anthropic

Set Default Provider

clawdius config set provider anthropic

Configuration File

Create ~/.config/clawdius/config.toml:

# General Settings
[general]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
max_tokens = 4096
temperature = 0.7

# API Keys (stored securely in keyring)
# Use: clawdius config set api_key YOUR_KEY

# Session Settings
[session]
auto_save = true
max_history = 1000
compaction_threshold = 50000

# Sandbox Settings
[sandbox]
default_tier = "standard"
allow_network = false
allowed_paths = ["~/projects"]

# Output Settings
[output]
format = "streaming"
theme = "dark"
show_token_count = true

# Graph-RAG Settings
[graph_rag]
enabled = true
max_files = 10000
embedding_model = "text-embedding-3-small"

# Plugin Settings
[plugins]
enabled = true
auto_update = false
trusted_sources = ["https://plugins.clawdius.dev"]

# Telemetry
[telemetry]
enabled = false
# Set to true to help improve Clawdius

Environment Variables

Provider Configuration

Anthropic Claude

[providers.anthropic]
api_key_env = "ANTHROPIC_API_KEY"
model = "claude-sonnet-4-20250514"
base_url = "https://api.anthropic.com"

[providers.anthropic.options]
max_tokens = 4096
temperature = 0.7

OpenAI

[providers.openai]
api_key_env = "OPENAI_API_KEY"
model = "gpt-4o"

[providers.openai.options]
max_tokens = 4096
temperature = 0.7

Ollama (Local)

[providers.ollama]
base_url = "http://localhost:11434"
model = "llama3.2"

[providers.ollama.options]
num_ctx = 4096
temperature = 0.7

Custom Provider

[providers.custom]
name = "my-provider"
base_url = "https://api.example.com/v1"
api_key_env = "MY_API_KEY"
model = "my-model"

[providers.custom.headers]
X-Custom-Header = "value"

Sandbox Configuration

Sandbox Tiers

[sandbox]
default_tier = "standard"

# Per-tier configuration
[sandbox.tiers.standard]
backend = "wasm"
memory_limit_mb = 512
cpu_limit_percent = 50

[sandbox.tiers.hardened]
backend = "bubblewrap"
network = false
filesystem = "readonly"

[sandbox.tiers.container]
backend = "docker"
image = "clawdius/sandbox:latest"

Path Allowlisting

[sandbox]
allowed_paths = [
    "~/projects",
    "~/src",
    "/tmp/clawdius"
]

# Read-only paths
read_only_paths = [
    "/usr/include",
    "~/.cargo/registry"
]

# Denied paths (always blocked)
denied_paths = [
    "~/.ssh",
    "~/.gnupg",
    "~/.config/clawdius/keys"
]

Session Configuration

[session]
# Auto-save sessions
auto_save = true
auto_save_interval_secs = 60

# History limits
max_history = 1000
max_context_tokens = 100000

# Compaction settings
compaction_threshold = 50000
compaction_strategy = "sliding_window"  # or "summarize"

Output Configuration

[output]
# Output format: streaming, batch, json
format = "streaming"

# Theme: dark, light, ansi
theme = "dark"

# Display options
show_token_count = true
show_timing = false
show_model = true

# Markdown rendering
markdown = true
code_highlighting = true

Plugin Configuration

[plugins]
enabled = true
directory = "~/.local/share/clawdius/plugins"
auto_update = false

# Trusted plugin sources
trusted_sources = [
    "https://plugins.clawdius.dev"
]

# Disabled plugins (by ID)
disabled = []

# Plugin-specific settings
[plugins.settings."my-plugin"]
option1 = "value1"
option2 = true

Enterprise Configuration

SSO

[enterprise.sso]
enabled = true
provider = "okta"  # okta, azure, github, custom

[enterprise.sso.okta]
domain = "your-company.okta.com"
client_id = "your-client-id"

[enterprise.sso.azure]
tenant_id = "your-tenant-id"
client_id = "your-client-id"

Audit Logging

[enterprise.audit]
enabled = true
backend = "sqlite"  # sqlite, elasticsearch, webhook

[enterprise.audit.sqlite]
path = "/var/log/clawdius/audit.db"

[enterprise.audit.elasticsearch]
url = "https://elasticsearch.example.com"
index = "clawdius-audit"

CLI Commands

# View current configuration
clawdius config list

# Set a value
clawdius config set <key> <value>

# Get a value
clawdius config get <key>

# Edit configuration file
clawdius config edit

# Reset to defaults
clawdius config reset

Next Steps

• First Chat - Start your first conversation
• Sandboxing - Learn about security tiers
• Enterprise SSO - Configure enterprise features

First Chat

Now that Clawdius is installed and configured, let's start your first conversation.

Starting a Chat Session

Interactive Mode

clawdius chat

This opens an interactive REPL where you can have a conversation:

╭─────────────────────────────────────────────────────────────────╮
│  Clawdius v1.0.0 - High-Assurance AI Coding Assistant          │
│  Provider: Anthropic (claude-sonnet-4-20250514)                 │
│  Sandbox: standard (WASM)                                       │
╰─────────────────────────────────────────────────────────────────╯

You: Hello! Can you help me write a Rust function to parse JSON?

Clawdius: I'd be happy to help! Here's a function that parses JSON using 
serde_json:

```rust
use serde_json::Value;

fn parse_json(input: &str) -> Result<Value, serde_json::Error> {
    serde_json::from_str(input)
}

You can use it like this: ...

### One-shot Mode

For quick questions:

```bash
clawdius chat --message "What is the difference between Vec and VecDeque in Rust?"

With File Context

# Include files for context
clawdius chat --file src/main.rs --file src/lib.rs

# Or include entire directory
clawdius chat --dir src/

Basic Commands

Inside the chat session:

Using @mentions

Clawdius supports @mentions to reference files, directories, or previous context:

You: Please review @src/main.rs and suggest improvements

You: What patterns are used in @src/ directory?

You: Based on our @previous discussion, implement the feature

You: Use @commit:abc123 as reference

Available Mentions

Modes

Clawdius has different modes optimized for different tasks:

Code Mode (default)

Optimized for writing and editing code:

clawdius chat --mode code

Architect Mode

High-level system design and planning:

clawdius chat --mode architect

Review Mode

Code review and quality analysis:

clawdius chat --mode review

Debug Mode

Debugging and troubleshooting:

clawdius chat --mode debug

File Operations

Clawdius can read, create, edit, and delete files:

You: Read the file src/main.rs and explain what it does

Clawdius: I'll read the file...

[Reads src/main.rs]

This file contains the main entry point for your application...

You: Create a new file src/utils.rs with helper functions

Clawdius: I'll create src/utils.rs with some utility functions...

[Creates src/utils.rs]

Created src/utils.rs with the following helper functions:
- `truncate_string` - Truncates a string to max length
- `format_bytes` - Formats bytes as human-readable string
...

You: Add a function to validate email addresses in src/utils.rs

Clawdius: I'll add an email validation function...

[Edits src/utils.rs]

Added `validate_email` function at line 45.

Git Operations

Clawdius can interact with git:

You: What changes have been made since the last commit?

Clawdius: I'll check the git status...

[Runs git status and git diff]

Modified files:
- src/main.rs (3 additions, 1 deletion)
- src/utils.rs (15 additions)

You: Commit these changes with a descriptive message

Clawdius: I'll commit these changes...

[Runs git add and git commit]

Committed: "Add utility functions and update main"
Commit hash: abc1234

Checkpoints and Undo

Clawdius tracks all changes and allows undo/redo:

You: /checkpoint

Clawdius: Created checkpoint "before-refactor" at 2024-01-15 10:30:00

You: Refactor the authentication module

Clawdius: I'll refactor the authentication module...

[Refactors auth module]

You: Actually, let me undo that

Clawdius: Undid the refactoring changes. Restored to checkpoint "before-refactor"

You: /redo

Clawdius: Redid the refactoring changes.

Session Management

Save Session

You: /save auth-feature

Clawdius: Session saved as "auth-feature"

Load Session

You: /load auth-feature

Clawdius: Loaded session "auth-feature" from 2024-01-15 10:30:00
Restored context: 5 files, 12 messages

List Sessions

clawdius session list

Export Session

clawdius session export auth-feature --format markdown

Tips for Effective Chats

1. Be specific: Provide context and clarify your requirements
2. Use @mentions: Reference relevant files and context
3. Use checkpoints: Create checkpoints before major changes
4. Review changes: Always review code changes before applying
5. Iterate: Start simple and refine through conversation

Next Steps

• Basic Usage - Learn more about daily workflows
• Tools - Understand available tools
• Modes - Deep dive into different modes

Basic Usage

Architecture Overview

Sandboxing

Sessions

Tools

Graph-RAG

Overview

Anthropic Claude

OpenAI

Ollama (Local)

Custom Providers

Checkpoints & Timeline

@mentions

Modes

Streaming

Keyring Storage

Overview

Sandbox Tiers

Backend Configuration

WASM

Bubblewrap

Container

gVisor

Firecracker

SSO Integration

Audit Logging

Compliance

Team Management

Overview

Creating Plugins

Plugin API

Hooks

Marketplace

VSCode

Vim/Neovim

Emacs

CLI Reference

API Stability

Rust API

JSON-RPC

Plugin API

Performance Tuning

Security Hardening

Self-Hosted Deployment

Formal Verification

Configuration Schema

CLI Commands

Error Codes

Glossary

Contributing

Code of Conduct

Changelog

Support