An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.
Rust
docs: add a current claw CLI usage guide
Yeachan-Heo953513f12d9f
diff --git a/README.md b/README.mdindex a74ce3b6..5d3ea090 100644--- a/README.md+++ b/README.md@@ -27,7 +27,7 @@</p>> [!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.mdnew file mode 100644index 00000000..f8232d6b--- /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. `<repo>/.claw.json`+4. `<repo>/.claw/settings.json`+5. `<repo>/.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.mdindex 2ddbf5c0..c087e0a7 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 commandscd rust/-cargo build --release+cargo run -p rusty-claude-cli -- --help++# Build the workspace+cargo build --workspace-# Run interactive REPL-./target/release/claw+# 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 locallyCommands:prompt <text> One-shot prompt (non-interactive)login Authenticate via OAuthlogout Clear stored credentialsinit 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.mdnew file mode 100644index 00000000..0fbf14b1--- /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