From 04b1f1e85d45480b078c0cb460e55d7a57799305 Mon Sep 17 00:00:00 2001 From: Yeachan-Heo Date: Wed, 1 Apr 2026 02:59:05 +0000 Subject: [PATCH] docs: rewrite rust/ README with full feature matrix and usage guide --- rust/README.md | 353 +++++++++++++++++++------------------------------ 1 file changed, 136 insertions(+), 217 deletions(-) diff --git a/rust/README.md b/rust/README.md index 26a0d4a..e3b5924 100644 --- a/rust/README.md +++ b/rust/README.md @@ -1,230 +1,149 @@ -# Rusty Claude CLI +# 🦞 Claw Code — Rust Implementation -`rust/` contains the Rust workspace for the integrated `rusty-claude-cli` deliverable. -It is intended to be something you can clone, build, and run directly. +A high-performance Rust rewrite of the Claude Code CLI agent harness. Built for speed, safety, and native tool execution. -## Workspace layout +## Quick Start -```text +```bash +# Build +cd rust/ +cargo build --release + +# Run interactive REPL +./target/release/claw + +# One-shot prompt +./target/release/claw prompt "explain this codebase" + +# With specific model +./target/release/claw --model sonnet prompt "fix the bug in 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: + +```bash +claw login +``` + +## Features + +| Feature | Status | +|---------|--------| +| Anthropic API + streaming | ✅ | +| OAuth login/logout | ✅ | +| Interactive REPL (rustyline) | ✅ | +| Tool system (bash, read, write, edit, grep, glob) | ✅ | +| Web tools (search, fetch) | ✅ | +| Sub-agent orchestration | ✅ | +| Todo tracking | ✅ | +| Notebook editing | ✅ | +| CLAUDE.md / project memory | ✅ | +| Config file hierarchy (.claude.json) | ✅ | +| Permission system | ✅ | +| MCP server lifecycle | ✅ | +| Session persistence + resume | ✅ | +| Extended thinking (thinking blocks) | ✅ | +| Cost tracking + usage display | ✅ | +| Git integration | ✅ | +| Markdown terminal rendering (ANSI) | ✅ | +| Model aliases (opus/sonnet/haiku) | ✅ | +| Slash commands (/status, /compact, /clear, etc.) | ✅ | +| Hooks (PreToolUse/PostToolUse) | 🔧 Config only | +| Plugin system | 📋 Planned | +| Skills registry | 📋 Planned | + +## 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 + +``` +claw [OPTIONS] [COMMAND] + +Options: + --model MODEL Set the model (alias or full name) + --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 + +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 +``` + +## Slash Commands (REPL) + +| Command | Description | +|---------|-------------| +| `/help` | Show help | +| `/status` | Show session status (model, tokens, cost) | +| `/cost` | Show cost breakdown | +| `/compact` | Compact conversation history | +| `/clear` | Clear conversation | +| `/model [name]` | Show or switch model | +| `/permissions` | Show or switch permission mode | +| `/config [section]` | Show config (env, hooks, model) | +| `/memory` | Show CLAUDE.md contents | +| `/diff` | Show git diff | +| `/export [path]` | Export conversation | +| `/session [id]` | Resume a previous session | +| `/version` | Show version | + +## Workspace Layout + +``` rust/ -├── Cargo.toml +├── Cargo.toml # Workspace root ├── Cargo.lock -├── README.md └── crates/ - ├── api/ # Anthropic API client + SSE streaming support - ├── commands/ # Shared slash-command metadata/help surfaces - ├── compat-harness/ # Upstream TS manifest extraction harness - ├── runtime/ # Session/runtime/config/prompt orchestration - ├── rusty-claude-cli/ # Main CLI binary - └── tools/ # Built-in tool implementations + ├── api/ # Anthropic API client + SSE streaming + ├── commands/ # Shared slash-command registry + ├── compat-harness/ # TS manifest extraction harness + ├── runtime/ # Session, config, permissions, MCP, prompts + ├── rusty-claude-cli/ # Main CLI binary (`claw`) + └── tools/ # Built-in tool implementations ``` -## Prerequisites +### Crate Responsibilities -- Rust toolchain installed (`rustup`, stable toolchain) -- Network access and Anthropic credentials for live prompt/REPL usage +- **api** — HTTP client, SSE stream parser, request/response types, auth (API key + OAuth bearer) +- **commands** — Slash command definitions and help text generation +- **compat-harness** — Extracts tool/prompt manifests from upstream TS source +- **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 +- **tools** — Tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, REPL runtimes -## Build +## Stats -From the repository root: +- **~20K lines** of Rust +- **6 crates** in workspace +- **Binary name:** `claw` +- **Default model:** `claude-opus-4-6` +- **Default permissions:** `danger-full-access` -```bash -cd rust -cargo build --release -p rusty-claude-cli -``` +## License -The optimized binary will be written to: - -```bash -./target/release/rusty-claude-cli -``` - -## Test - -Run the verified workspace test suite used for release-readiness: - -```bash -cd rust -cargo test --workspace --exclude compat-harness -``` - -## Quick start - -### Show help - -```bash -cd rust -cargo run -p rusty-claude-cli -- --help -``` - -### Print version - -```bash -cd rust -cargo run -p rusty-claude-cli -- --version -``` - -### Login with OAuth - -Configure `settings.json` with an `oauth` block containing `clientId`, `authorizeUrl`, `tokenUrl`, optional `callbackPort`, and optional `scopes`, then run: - -```bash -cd rust -cargo run -p rusty-claude-cli -- login -``` - -This opens the browser, listens on the configured localhost callback, exchanges the auth code for tokens, and stores OAuth credentials in `~/.claude/credentials.json` (or `$CLAUDE_CONFIG_HOME/credentials.json`). - -### Logout - -```bash -cd rust -cargo run -p rusty-claude-cli -- logout -``` - -This removes only the stored OAuth credentials and preserves unrelated JSON fields in `credentials.json`. - -### Self-update - -```bash -cd rust -cargo run -p rusty-claude-cli -- self-update -``` - -The command checks the latest GitHub release for `instructkr/clawd-code`, compares it to the current binary version, downloads the matching binary asset plus checksum manifest, verifies SHA-256, replaces the current executable, and prints the release changelog. If no published release or matching asset exists, it exits safely with an explanatory message. - -## Usage examples - -### 1) Prompt mode - -Send one prompt, stream the answer, then exit: - -```bash -cd rust -cargo run -p rusty-claude-cli -- prompt "Summarize the architecture of this repository" -``` - -Use a specific model: - -```bash -cd rust -cargo run -p rusty-claude-cli -- --model claude-sonnet-4-20250514 prompt "List the key crates in this workspace" -``` - -Restrict enabled tools in an interactive session: - -```bash -cd rust -cargo run -p rusty-claude-cli -- --allowedTools read,glob -``` - -Bootstrap Claude project files for the current repo: - -```bash -cd rust -cargo run -p rusty-claude-cli -- init -``` - -### 2) REPL mode - -Start the interactive shell: - -```bash -cd rust -cargo run -p rusty-claude-cli -- -``` - -Inside the REPL, useful commands include: - -```text -/help -/status -/model claude-sonnet-4-20250514 -/permissions workspace-write -/cost -/compact -/memory -/config -/init -/diff -/version -/export notes.txt -/sessions -/session list -/exit -``` - -### 3) Resume an existing session - -Inspect or maintain a saved session file without entering the REPL: - -```bash -cd rust -cargo run -p rusty-claude-cli -- --resume session-123456 /status /compact /cost -``` - -You can also inspect memory/config state for a restored session: - -```bash -cd rust -cargo run -p rusty-claude-cli -- --resume ~/.claude/sessions/session-123456.json /memory /config -``` - -## Available commands - -### Top-level CLI commands - -- `prompt ` — run one prompt non-interactively -- `--resume [/commands...]` — inspect or maintain a saved session stored under `~/.claude/sessions/` -- `dump-manifests` — print extracted upstream manifest counts -- `bootstrap-plan` — print the current bootstrap skeleton -- `system-prompt [--cwd PATH] [--date YYYY-MM-DD]` — render the synthesized system prompt -- `self-update` — update the installed binary from the latest GitHub release when a matching asset is available -- `--help` / `-h` — show CLI help -- `--version` / `-V` — print the CLI version and build info locally (no API call) -- `--output-format text|json` — choose non-interactive prompt output rendering -- `--allowedTools ` — restrict enabled tools for interactive sessions and prompt-mode tool use - -### Interactive slash commands - -- `/help` — show command help -- `/status` — show current session status -- `/compact` — compact local session history -- `/model [model]` — inspect or switch the active model -- `/permissions [read-only|workspace-write|danger-full-access]` — inspect or switch permissions -- `/clear [--confirm]` — clear the current local session -- `/cost` — show token usage totals -- `/resume ` — load a saved session into the REPL -- `/config [env|hooks|model]` — inspect discovered Claude config -- `/memory` — inspect loaded instruction memory files -- `/init` — bootstrap `.claude.json`, `.claude/`, `CLAUDE.md`, and local ignore rules -- `/diff` — show the current git diff for the workspace -- `/version` — print version and build metadata locally -- `/export [file]` — export the current conversation transcript -- `/sessions` — list recent managed local sessions from `~/.claude/sessions/` -- `/session [list|switch ]` — inspect or switch managed local sessions -- `/exit` — leave the REPL - -## Environment variables - -### Anthropic/API - -- `ANTHROPIC_API_KEY` — highest-precedence API credential -- `ANTHROPIC_AUTH_TOKEN` — bearer-token override used when no API key is set -- Persisted OAuth credentials in `~/.claude/credentials.json` — used when neither env var is set -- `ANTHROPIC_BASE_URL` — override the Anthropic API base URL -- `ANTHROPIC_MODEL` — default model used by selected live integration tests - -### CLI/runtime - -- `RUSTY_CLAUDE_PERMISSION_MODE` — default REPL permission mode (`read-only`, `workspace-write`, or `danger-full-access`) -- `CLAUDE_CONFIG_HOME` — override Claude config discovery root -- `CLAUDE_CODE_REMOTE` — enable remote-session bootstrap handling when supported -- `CLAUDE_CODE_REMOTE_SESSION_ID` — remote session identifier when using remote mode -- `CLAUDE_CODE_UPSTREAM` — override the upstream TS source path for compat-harness extraction -- `CLAWD_WEB_SEARCH_BASE_URL` — override the built-in web search service endpoint used by tooling - -## Notes - -- `compat-harness` exists to compare the Rust port against the upstream TypeScript codebase and is intentionally excluded from the requested release test run. -- The CLI currently focuses on a practical integrated workflow: prompt execution, REPL operation, session inspection/resume, config discovery, and tool/runtime plumbing. +See repository root.