claw-code/rust/README.md

218 lines
7.4 KiB
Markdown

# ๐Ÿฆž Claw Code โ€” Rust Implementation
A high-performance Rust rewrite of the Claw Code CLI agent harness. Built for speed, safety, and native tool execution.
For a task-oriented guide with copy/paste examples, see [`../USAGE.md`](../USAGE.md).
## Quick Start
```bash
# Inspect available commands
cd rust/
cargo run -p rusty-claude-cli -- --help
# Build the workspace
cargo build --workspace
# Run the interactive REPL
cargo run -p rusty-claude-cli -- --model claude-opus-4-6
# One-shot prompt
cargo run -p rusty-claude-cli -- prompt "explain this codebase"
# JSON output for automation
cargo run -p rusty-claude-cli -- --output-format json prompt "summarize src/main.rs"
```
## Configuration
Set your API credentials:
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
# Or use a proxy
export ANTHROPIC_BASE_URL="https://your-proxy.com"
```
Or authenticate via OAuth and let the CLI persist credentials locally:
```bash
cargo run -p rusty-claude-cli -- login
```
## Mock parity harness
The workspace now includes a deterministic Anthropic-compatible mock service and a clean-environment CLI harness for end-to-end parity checks.
```bash
cd rust/
# Run the scripted clean-environment harness
./scripts/run_mock_parity_harness.sh
# Or start the mock service manually for ad hoc CLI runs
cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0
```
Harness coverage:
- `streaming_text`
- `read_file_roundtrip`
- `grep_chunk_assembly`
- `write_file_allowed`
- `write_file_denied`
- `multi_tool_turn_roundtrip`
- `bash_stdout_roundtrip`
- `bash_permission_prompt_approved`
- `bash_permission_prompt_denied`
- `plugin_tool_roundtrip`
Primary artifacts:
- `crates/mock-anthropic-service/` โ€” reusable mock Anthropic-compatible service
- `crates/rusty-claude-cli/tests/mock_parity_harness.rs` โ€” clean-env CLI harness
- `scripts/run_mock_parity_harness.sh` โ€” reproducible wrapper
- `scripts/run_mock_parity_diff.py` โ€” scenario checklist + PARITY mapping runner
- `mock_parity_scenarios.json` โ€” scenario-to-PARITY manifest
## Features
| Feature | Status |
|---------|--------|
| Anthropic / OpenAI-compatible provider flows + streaming | โœ… |
| OAuth login/logout | โœ… |
| Interactive REPL (rustyline) | โœ… |
| Tool system (bash, read, write, edit, grep, glob) | โœ… |
| Web tools (search, fetch) | โœ… |
| Sub-agent / agent surfaces | โœ… |
| Todo tracking | โœ… |
| Notebook editing | โœ… |
| CLAUDE.md / project memory | โœ… |
| Config file hierarchy (`.claw.json` + merged config sections) | โœ… |
| Permission system | โœ… |
| MCP server lifecycle + inspection | โœ… |
| Session persistence + resume | โœ… |
| Cost / usage / stats surfaces | โœ… |
| Git integration | โœ… |
| Markdown terminal rendering (ANSI) | โœ… |
| Model aliases (opus/sonnet/haiku) | โœ… |
| Direct CLI subcommands (`status`, `sandbox`, `agents`, `mcp`, `skills`, `doctor`) | โœ… |
| Slash commands (including `/skills`, `/agents`, `/mcp`, `/doctor`, `/plugin`, `/subagent`) | โœ… |
| Hooks (`/hooks`, config-backed lifecycle hooks) | โœ… |
| Plugin management surfaces | โœ… |
| Skills inventory / install surfaces | โœ… |
| Machine-readable JSON output across core CLI surfaces | โœ… |
## Model Aliases
Short names resolve to the latest model versions:
| Alias | Resolves To |
|-------|------------|
| `opus` | `claude-opus-4-6` |
| `sonnet` | `claude-sonnet-4-6` |
| `haiku` | `claude-haiku-4-5-20251213` |
## CLI Flags and Commands
Representative current surface:
```text
claw [OPTIONS] [COMMAND]
Flags:
--model MODEL
--output-format text|json
--permission-mode MODE
--dangerously-skip-permissions
--allowedTools TOOLS
--resume [SESSION.jsonl|session-id|latest]
--version, -V
Top-level commands:
prompt <text>
help
version
status
sandbox
dump-manifests
bootstrap-plan
agents
mcp
skills
system-prompt
login
logout
init
```
The command surface is moving quickly. For the canonical live help text, run:
```bash
cargo run -p rusty-claude-cli -- --help
```
## Slash Commands (REPL)
Tab completion expands slash commands, model aliases, permission modes, and recent session IDs.
The REPL now exposes a much broader surface than the original minimal shell:
- session / visibility: `/help`, `/status`, `/sandbox`, `/cost`, `/resume`, `/session`, `/version`, `/usage`, `/stats`
- workspace / git: `/compact`, `/clear`, `/config`, `/memory`, `/init`, `/diff`, `/commit`, `/pr`, `/issue`, `/export`, `/hooks`, `/files`, `/branch`, `/release-notes`, `/add-dir`
- discovery / debugging: `/mcp`, `/agents`, `/skills`, `/doctor`, `/tasks`, `/context`, `/desktop`, `/ide`
- automation / analysis: `/review`, `/advisor`, `/insights`, `/security-review`, `/subagent`, `/team`, `/telemetry`, `/providers`, `/cron`, and more
- plugin management: `/plugin` (with aliases `/plugins`, `/marketplace`)
Notable claw-first surfaces now available directly in slash form:
- `/skills [list|install <path>|help]`
- `/agents [list|help]`
- `/mcp [list|show <server>|help]`
- `/doctor`
- `/plugin [list|install <path>|enable <name>|disable <name>|uninstall <id>|update <id>]`
- `/subagent [list|steer <target> <msg>|kill <id>]`
See [`../USAGE.md`](../USAGE.md) for usage examples and run `cargo run -p rusty-claude-cli -- --help` for the live canonical command list.
## Workspace Layout
```text
rust/
โ”œโ”€โ”€ Cargo.toml # Workspace root
โ”œโ”€โ”€ Cargo.lock
โ””โ”€โ”€ crates/
โ”œโ”€โ”€ api/ # Provider clients + streaming + request preflight
โ”œโ”€โ”€ commands/ # Shared slash-command registry + help rendering
โ”œโ”€โ”€ compat-harness/ # TS manifest extraction harness
โ”œโ”€โ”€ mock-anthropic-service/ # Deterministic local Anthropic-compatible mock
โ”œโ”€โ”€ plugins/ # Plugin metadata, manager, install/enable/disable surfaces
โ”œโ”€โ”€ runtime/ # Session, config, permissions, MCP, prompts, auth/runtime loop
โ”œโ”€โ”€ rusty-claude-cli/ # Main CLI binary (`claw`)
โ”œโ”€โ”€ telemetry/ # Session tracing and usage telemetry types
โ””โ”€โ”€ tools/ # Built-in tools, skill resolution, tool search, agent runtime surfaces
```
### Crate Responsibilities
- **api** โ€” provider clients, SSE streaming, request/response types, auth (API key + OAuth bearer), request-size/context-window preflight
- **commands** โ€” slash command definitions, parsing, help text generation, JSON/text command rendering
- **compat-harness** โ€” extracts tool/prompt manifests from upstream TS source
- **mock-anthropic-service** โ€” deterministic `/v1/messages` mock for CLI parity tests and local harness runs
- **plugins** โ€” plugin metadata, install/enable/disable/update flows, plugin tool definitions, hook integration surfaces
- **runtime** โ€” `ConversationRuntime`, config loading, session persistence, permission policy, MCP client lifecycle, system prompt assembly, usage tracking
- **rusty-claude-cli** โ€” REPL, one-shot prompt, direct CLI subcommands, streaming display, tool call rendering, CLI argument parsing
- **telemetry** โ€” session trace events and supporting telemetry payloads
- **tools** โ€” tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, and runtime-facing tool discovery
## Stats
- **~20K lines** of Rust
- **9 crates** in workspace
- **Binary name:** `claw`
- **Default model:** `claude-opus-4-6`
- **Default permissions:** `danger-full-access`
## License
See repository root.