claudecode/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claw Code is a local coding-agent CLI tool written in safe Rust. It is a clean-room implementation inspired by Claude Code, providing an interactive REPL, one-shot prompts, workspace-aware tools, local agent workflows, and plugin support. The project name and references throughout use "claw" / "Claw Code".

Build & Run Commands

# Build release binary (produces target/release/claw)
cargo build --release -p claw-cli

# Run from source (interactive REPL)
cargo run --bin claw --

# Run one-shot prompt
cargo run --bin claw -- prompt "summarize this workspace"

# Install locally
cargo install --path crates/claw-cli --locked

# Run the HTTP server binary
cargo run --bin claw-server

Verification Commands

# Format check
cargo fmt

# Lint (workspace-level clippy with deny warnings)
cargo clippy --workspace --all-targets -- -D warnings

# Run all tests
cargo test --workspace

# Run tests for a specific crate
cargo test -p api
cargo test -p runtime

# Run a single test by name
cargo test -p <crate> -- <test_name>

# Integration tests in crates/api/tests/ use mock TCP servers (no network needed)
# One smoke test is #[ignore] — run with: cargo test -p api -- --ignored

Workspace Architecture

Cargo workspace with resolver = "2". All crates live under crates/.

Crate Dependency Graph

claw-cli  ──→  api, runtime, tools, commands, plugins, compat-harness
server    ──→  api, runtime, tools, plugins, commands
tools     ──→  api, runtime, plugins
commands  ──→  runtime, plugins
api       ──→  runtime
runtime   ──→  lsp, plugins
plugins   ──→  (standalone, serde only)
lsp       ──→  (standalone)
compat-harness ──→  commands, tools, runtime

Core Crates

• claw-cli — User-facing binary (claw). REPL loop with markdown rendering (pulldown-cmark + syntect), argument parsing, OAuth flow. Entry point: crates/claw-cli/src/main.rs.

• runtime — Session management, conversation runtime, permissions, system prompt construction, context compaction, MCP stdio management, and hook execution. Key types: Session (versioned message history), ConversationRuntime<C, T> (generic over ApiClient + ToolExecutor traits), PermissionMode, McpServerManager, HookRunner.

• api — HTTP client for LLM providers with SSE streaming. ClawApiClient (Anthropic-compatible), OpenAiCompatClient, and Provider trait. ProviderKind enum distinguishes ClawApi, Xai, OpenAi. Request/response types: MessageRequest, StreamEvent, ToolDefinition.

• tools — Built-in tool definitions and dispatch. GlobalToolRegistry is a lazy-static singleton. Tools: Read, Write, Edit, Glob, Grep, Bash, LSP, Task*, Cron*, Worktree*. Each tool has a ToolSpec with JSON schema.

• commands — Slash command registry and handlers (/help, /config, /compact, /resume, /plugins, /agents, /doctor, etc.). SlashCommandSpec defines each command's name, aliases, description, and category.

• plugins — Plugin discovery and lifecycle. PluginManager loads builtin, bundled, and external (from ~/.claw/plugins/) plugins. Plugins can provide additional tools via PluginTool.

• server — Axum-based HTTP server (claw-server). REST endpoints for session CRUD + SSE event streaming. AppState holds shared session store.

• lsp — Language Server Protocol types and process management for code intelligence features.

• compat-harness — Extracts command/tool/bootstrap-plan manifests from upstream TypeScript source files (for compatibility tracking). Uses CLAUDE_CODE_UPSTREAM env var to locate the upstream repo.

Key Architectural Patterns

• Trait-based abstraction: ApiClient, ToolExecutor, Provider traits enable swappable implementations. ConversationRuntime is generic over client and executor.
• Static registries: GlobalToolRegistry and slash command specs use lazy-static initialization with compile-time definitions.
• SSE streaming: API responses stream through MessageStream (async iterator) to the terminal renderer or server SSE endpoints.
• Permission model: PermissionMode enum — ReadOnly, WorkspaceWrite, DangerFullAccess. Configurable via .claw.json (permissions.defaultMode).
• Hook system: Pre/post tool execution hooks via HookRunner in the runtime crate.

Configuration & Environment

• .claw.json — Project-level config (permissions, etc.)
• .claw/ — Project directory for hooks, plugins, local settings
• ~/.claw/ — User-level config directory
• .env — API keys (gitignored): ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, XAI_API_KEY, XAI_BASE_URL
• CLAW.md — Workspace instructions loaded into the system prompt (analogous to CLAUDE.md but for claw itself)

Lint Rules

• unsafe_code is forbidden at workspace level
• Clippy all + pedantic lints are warnings; some pedantic lints are allowed (module_name_repetitions, missing_panics_doc, missing_errors_doc)
• CI runs: cargo check --workspace, cargo test --workspace, cargo build --release on Ubuntu and macOS

Language

Code comments, commit messages, and documentation are primarily in Chinese (中文). UI strings and exported symbol names are in English.