eeymoo/claw-code
1
0
Fork 0
mirror of https://github.com/instructkr/claw-code.git synced 2026-04-05 23:54:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add a current claw CLI usage guide

Browse Source 
The root and Rust-facing docs now point readers at a single task-oriented usage guide with build, auth, CLI, session, and parity-harness examples. This also fixes stale workspace references and updates the Rust workspace inventory to match the current crate set.

Constraint: Existing README copy still referenced the old dev/rust status and needed to stay lightweight
Rejected: Fold all usage details into README.md only | too much noise for the landing page
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep USAGE examples aligned with  when CLI flags change
Tested: cargo build --workspace; cargo test --workspace
Not-tested: External links and rendered Markdown in GitHub UI
This commit is contained in:
Yeachan-Heo
2026-04-04 15:23:22 +00:00
parent fbb2275ab4
commit 953513f12d
4 changed files with 206 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -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.

159
USAGE.md Normal file
View File

@@ -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`

51
rust/README.md
View File

@@ -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 <text> 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`

11
rust/USAGE.md Normal file
View File

@@ -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