diff --git a/README.md b/README.md index a74ce3b..5d3ea09 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@

> [!IMPORTANT] -> **Rust port is now in progress** on the [`dev/rust`](https://github.com/instructkr/claw-code/tree/dev/rust) branch and is expected to be merged into main today. The Rust implementation aims to deliver a faster, memory-safe harness runtime. Stay tuned — this will be the definitive version of the project. +> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, then use [`rust/README.md`](./rust/README.md) for crate-level details. > If you find this work useful, consider [sponsoring @instructkr on GitHub](https://github.com/sponsors/instructkr) to support continued open-source harness engineering research. diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..f8232d6 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,159 @@ +# Claw Code Usage + +This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary. + +## Prerequisites + +- Rust toolchain with `cargo` +- One of: + - `ANTHROPIC_API_KEY` for direct API access + - `claw login` for OAuth-based auth +- Optional: `ANTHROPIC_BASE_URL` when targeting a proxy or local service + +## Build the workspace + +```bash +cd rust +cargo build --workspace +``` + +The CLI binary is available at `rust/target/debug/claw` after a debug build. + +## Quick start + +### Interactive REPL + +```bash +cd rust +./target/debug/claw +``` + +### One-shot prompt + +```bash +cd rust +./target/debug/claw prompt "summarize this repository" +``` + +### Shorthand prompt mode + +```bash +cd rust +./target/debug/claw "explain rust/crates/runtime/src/lib.rs" +``` + +### JSON output for scripting + +```bash +cd rust +./target/debug/claw --output-format json prompt "status" +``` + +## Model and permission controls + +```bash +cd rust +./target/debug/claw --model sonnet prompt "review this diff" +./target/debug/claw --permission-mode read-only prompt "summarize Cargo.toml" +./target/debug/claw --permission-mode workspace-write prompt "update README.md" +./target/debug/claw --allowedTools read,glob "inspect the runtime crate" +``` + +Supported permission modes: + +- `read-only` +- `workspace-write` +- `danger-full-access` + +Model aliases currently supported by the CLI: + +- `opus` → `claude-opus-4-6` +- `sonnet` → `claude-sonnet-4-6` +- `haiku` → `claude-haiku-4-5-20251213` + +## Authentication + +### API key + +```bash +export ANTHROPIC_API_KEY="sk-ant-..." +``` + +### OAuth + +```bash +cd rust +./target/debug/claw login +./target/debug/claw logout +``` + +## Common operational commands + +```bash +cd rust +./target/debug/claw status +./target/debug/claw sandbox +./target/debug/claw agents +./target/debug/claw mcp +./target/debug/claw skills +./target/debug/claw system-prompt --cwd .. --date 2026-04-04 +``` + +## Session management + +REPL turns are persisted under `.claw/sessions/` in the current workspace. + +```bash +cd rust +./target/debug/claw --resume latest +./target/debug/claw --resume latest /status /diff +``` + +Useful interactive commands include `/help`, `/status`, `/cost`, `/config`, `/session`, `/model`, `/permissions`, and `/export`. + +## Config file resolution order + +Runtime config is loaded in this order, with later entries overriding earlier ones: + +1. `~/.claw.json` +2. `~/.config/claw/settings.json` +3. `/.claw.json` +4. `/.claw/settings.json` +5. `/.claw/settings.local.json` + +## Mock parity harness + +The workspace includes a deterministic Anthropic-compatible mock service and parity harness. + +```bash +cd rust +./scripts/run_mock_parity_harness.sh +``` + +Manual mock service startup: + +```bash +cd rust +cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0 +``` + +## Verification + +```bash +cd rust +cargo test --workspace +``` + +## Workspace overview + +Current Rust crates: + +- `api` +- `commands` +- `compat-harness` +- `mock-anthropic-service` +- `plugins` +- `runtime` +- `rusty-claude-cli` +- `telemetry` +- `tools` diff --git a/rust/README.md b/rust/README.md index 2ddbf5c..c087e0a 100644 --- a/rust/README.md +++ b/rust/README.md @@ -2,21 +2,26 @@ 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 -# Build +# Inspect available commands cd rust/ -cargo build --release +cargo run -p rusty-claude-cli -- --help -# Run interactive REPL -./target/release/claw +# Build the workspace +cargo build --workspace + +# Run the interactive REPL +cargo run -p rusty-claude-cli -- --model claude-opus-4-6 # One-shot prompt -./target/release/claw prompt "explain this codebase" +cargo run -p rusty-claude-cli -- prompt "explain this codebase" -# With specific model -./target/release/claw --model sonnet prompt "fix the bug in main.rs" +# JSON output for automation +cargo run -p rusty-claude-cli -- --output-format json prompt "summarize src/main.rs" ``` ## Configuration @@ -29,10 +34,10 @@ export ANTHROPIC_API_KEY="sk-ant-..." export ANTHROPIC_BASE_URL="https://your-proxy.com" ``` -Or authenticate via OAuth: +Or authenticate via OAuth and let the CLI persist credentials locally: ```bash -claw login +cargo run -p rusty-claude-cli -- login ``` ## Mock parity harness @@ -113,25 +118,32 @@ Short names resolve to the latest model versions: claw [OPTIONS] [COMMAND] Options: - --model MODEL Set the model (alias or full name) + --model MODEL Override the active model --dangerously-skip-permissions Skip all permission checks --permission-mode MODE Set read-only, workspace-write, or danger-full-access --allowedTools TOOLS Restrict enabled tools - --output-format FORMAT Output format (text or json) - --version, -V Print version info + --output-format FORMAT Non-interactive output format (text or json) + --resume SESSION Re-open a saved session or inspect it with slash commands + --version, -V Print version and build information locally Commands: prompt One-shot prompt (non-interactive) login Authenticate via OAuth logout Clear stored credentials init Initialize project config - doctor Check environment health - self-update Update to latest version + status Show the current workspace status snapshot + sandbox Show the current sandbox isolation snapshot + agents Inspect agent definitions + mcp Inspect configured MCP servers + skills Inspect installed skills + system-prompt Render the assembled system prompt ``` +For the current canonical help text, run `cargo run -p rusty-claude-cli -- --help`. + ## Slash Commands (REPL) -Tab completion now expands not just slash command names, but also common workflow arguments like model aliases, permission modes, and recent session IDs. +Tab completion expands slash commands, model aliases, permission modes, and recent session IDs. | Command | Description | |---------|-------------| @@ -146,9 +158,12 @@ Tab completion now expands not just slash command names, but also common workflo | `/memory` | Show CLAUDE.md contents | | `/diff` | Show git diff | | `/export [path]` | Export conversation | +| `/resume [id]` | Resume a saved conversation | | `/session [id]` | Resume a previous session | | `/version` | Show version | +See [`../USAGE.md`](../USAGE.md) for examples covering interactive use, JSON automation, sessions, permissions, and the mock parity harness. + ## Workspace Layout ``` @@ -160,8 +175,10 @@ rust/ ├── commands/ # Shared slash-command registry ├── compat-harness/ # TS manifest extraction harness ├── mock-anthropic-service/ # Deterministic local Anthropic-compatible mock + ├── plugins/ # Plugin registry and hook wiring primitives ├── runtime/ # Session, config, permissions, MCP, prompts ├── rusty-claude-cli/ # Main CLI binary (`claw`) + ├── telemetry/ # Session tracing and usage telemetry types └── tools/ # Built-in tool implementations ``` @@ -171,14 +188,16 @@ rust/ - **commands** — Slash command definitions and help text generation - **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, registries, and hook integration surfaces - **runtime** — `ConversationRuntime` agentic loop, `ConfigLoader` hierarchy, `Session` persistence, permission policy, MCP client, system prompt assembly, usage tracking - **rusty-claude-cli** — REPL, one-shot prompt, 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, REPL runtimes ## Stats - **~20K lines** of Rust -- **7 crates** in workspace +- **9 crates** in workspace - **Binary name:** `claw` - **Default model:** `claude-opus-4-6` - **Default permissions:** `danger-full-access` diff --git a/rust/USAGE.md b/rust/USAGE.md new file mode 100644 index 0000000..0fbf14b --- /dev/null +++ b/rust/USAGE.md @@ -0,0 +1,11 @@ +# Rust usage guide + +The canonical task-oriented usage guide lives at [`../USAGE.md`](../USAGE.md). + +Use that guide for: + +- workspace build and test commands +- authentication setup +- interactive and one-shot `claw` examples +- session resume workflows +- mock parity harness commands