# 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

```bash
# 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

```bash
# 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.