Skip to content

Commit 04b1f1e

Browse files
Yeachan-HeoYeachan-Heo
committed
docs: rewrite rust/ README with full feature matrix and usage guide
1 parent ac95f03 commit 04b1f1e

1 file changed

Lines changed: 124 additions & 205 deletions

File tree

‎rust/README.md‎

Lines changed: 124 additions & 205 deletions
Original file line numberDiff line numberDiff line change
@@ -1,230 +1,149 @@
1-
# Rusty Claude CLI
1+
# 🦞 Claw Code — Rust Implementation
22

3-
`rust/` contains the Rust workspace for the integrated `rusty-claude-cli` deliverable.
4-
It is intended to be something you can clone, build, and run directly.
3+
A high-performance Rust rewrite of the Claude Code CLI agent harness. Built for speed, safety, and native tool execution.
54

6-
## Workspace layout
7-
8-
```text
9-
rust/
10-
├── Cargo.toml
11-
├── Cargo.lock
12-
├── README.md
13-
└── crates/
14-
├── api/ # Anthropic API client + SSE streaming support
15-
├── commands/ # Shared slash-command metadata/help surfaces
16-
├── compat-harness/ # Upstream TS manifest extraction harness
17-
├── runtime/ # Session/runtime/config/prompt orchestration
18-
├── rusty-claude-cli/ # Main CLI binary
19-
└── tools/ # Built-in tool implementations
20-
```
21-
22-
## Prerequisites
23-
24-
- Rust toolchain installed (`rustup`, stable toolchain)
25-
- Network access and Anthropic credentials for live prompt/REPL usage
26-
27-
## Build
28-
29-
From the repository root:
30-
31-
```bash
32-
cd rust
33-
cargo build --release -p rusty-claude-cli
34-
```
35-
36-
The optimized binary will be written to:
5+
## Quick Start
376

387
```bash
39-
./target/release/rusty-claude-cli
40-
```
8+
# Build
9+
cd rust/
10+
cargo build --release
4111

42-
## Test
12+
# Run interactive REPL
13+
./target/release/claw
4314

44-
Run the verified workspace test suite used for release-readiness:
15+
# One-shot prompt
16+
./target/release/claw prompt "explain this codebase"
4517

46-
```bash
47-
cd rust
48-
cargo test --workspace --exclude compat-harness
18+
# With specific model
19+
./target/release/claw --model sonnet prompt "fix the bug in main.rs"
4920
```
5021

51-
## Quick start
22+
## Configuration
5223

53-
### Show help
24+
Set your API credentials:
5425

5526
```bash
56-
cd rust
57-
cargo run -p rusty-claude-cli -- --help
27+
export ANTHROPIC_API_KEY="sk-ant-..."
28+
# Or use a proxy
29+
export ANTHROPIC_BASE_URL="https://your-proxy.com"
5830
```
5931

60-
### Print version
32+
Or authenticate via OAuth:
6133

6234
```bash
63-
cd rust
64-
cargo run -p rusty-claude-cli -- --version
65-
```
35+
claw login
36+
```
37+
38+
## Features
39+
40+
| Feature | Status |
41+
|---------|--------|
42+
| Anthropic API + streaming | ✅ |
43+
| OAuth login/logout | ✅ |
44+
| Interactive REPL (rustyline) | ✅ |
45+
| Tool system (bash, read, write, edit, grep, glob) | ✅ |
46+
| Web tools (search, fetch) | ✅ |
47+
| Sub-agent orchestration | ✅ |
48+
| Todo tracking | ✅ |
49+
| Notebook editing | ✅ |
50+
| CLAUDE.md / project memory | ✅ |
51+
| Config file hierarchy (.claude.json) | ✅ |
52+
| Permission system | ✅ |
53+
| MCP server lifecycle | ✅ |
54+
| Session persistence + resume | ✅ |
55+
| Extended thinking (thinking blocks) | ✅ |
56+
| Cost tracking + usage display | ✅ |
57+
| Git integration | ✅ |
58+
| Markdown terminal rendering (ANSI) | ✅ |
59+
| Model aliases (opus/sonnet/haiku) | ✅ |
60+
| Slash commands (/status, /compact, /clear, etc.) | ✅ |
61+
| Hooks (PreToolUse/PostToolUse) | 🔧 Config only |
62+
| Plugin system | 📋 Planned |
63+
| Skills registry | 📋 Planned |
64+
65+
## Model Aliases
66+
67+
Short names resolve to the latest model versions:
68+
69+
| Alias | Resolves To |
70+
|-------|------------|
71+
| `opus` | `claude-opus-4-6` |
72+
| `sonnet` | `claude-sonnet-4-6` |
73+
| `haiku` | `claude-haiku-4-5-20251213` |
74+
75+
## CLI Flags
76+
77+
```
78+
claw [OPTIONS] [COMMAND]
79+
80+
Options:
81+
--model MODEL Set the model (alias or full name)
82+
--dangerously-skip-permissions Skip all permission checks
83+
--permission-mode MODE Set read-only, workspace-write, or danger-full-access
84+
--allowedTools TOOLS Restrict enabled tools
85+
--output-format FORMAT Output format (text or json)
86+
--version, -V Print version info
87+
88+
Commands:
89+
prompt <text> One-shot prompt (non-interactive)
90+
login Authenticate via OAuth
91+
logout Clear stored credentials
92+
init Initialize project config
93+
doctor Check environment health
94+
self-update Update to latest version
95+
```
96+
97+
## Slash Commands (REPL)
98+
99+
| Command | Description |
100+
|---------|-------------|
101+
| `/help` | Show help |
102+
| `/status` | Show session status (model, tokens, cost) |
103+
| `/cost` | Show cost breakdown |
104+
| `/compact` | Compact conversation history |
105+
| `/clear` | Clear conversation |
106+
| `/model [name]` | Show or switch model |
107+
| `/permissions` | Show or switch permission mode |
108+
| `/config [section]` | Show config (env, hooks, model) |
109+
| `/memory` | Show CLAUDE.md contents |
110+
| `/diff` | Show git diff |
111+
| `/export [path]` | Export conversation |
112+
| `/session [id]` | Resume a previous session |
113+
| `/version` | Show version |
114+
115+
## Workspace Layout
66116

67-
### Login with OAuth
68-
69-
Configure `settings.json` with an `oauth` block containing `clientId`, `authorizeUrl`, `tokenUrl`, optional `callbackPort`, and optional `scopes`, then run:
70-
71-
```bash
72-
cd rust
73-
cargo run -p rusty-claude-cli -- login
74-
```
75-
76-
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`).
77-
78-
### Logout
79-
80-
```bash
81-
cd rust
82-
cargo run -p rusty-claude-cli -- logout
83117
```
84-
85-
This removes only the stored OAuth credentials and preserves unrelated JSON fields in `credentials.json`.
86-
87-
### Self-update
88-
89-
```bash
90-
cd rust
91-
cargo run -p rusty-claude-cli -- self-update
92-
```
93-
94-
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.
95-
96-
## Usage examples
97-
98-
### 1) Prompt mode
99-
100-
Send one prompt, stream the answer, then exit:
101-
102-
```bash
103-
cd rust
104-
cargo run -p rusty-claude-cli -- prompt "Summarize the architecture of this repository"
105-
```
106-
107-
Use a specific model:
108-
109-
```bash
110-
cd rust
111-
cargo run -p rusty-claude-cli -- --model claude-sonnet-4-20250514 prompt "List the key crates in this workspace"
112-
```
113-
114-
Restrict enabled tools in an interactive session:
115-
116-
```bash
117-
cd rust
118-
cargo run -p rusty-claude-cli -- --allowedTools read,glob
119-
```
120-
121-
Bootstrap Claude project files for the current repo:
122-
123-
```bash
124-
cd rust
125-
cargo run -p rusty-claude-cli -- init
126-
```
127-
128-
### 2) REPL mode
129-
130-
Start the interactive shell:
131-
132-
```bash
133-
cd rust
134-
cargo run -p rusty-claude-cli --
135-
```
136-
137-
Inside the REPL, useful commands include:
138-
139-
```text
140-
/help
141-
/status
142-
/model claude-sonnet-4-20250514
143-
/permissions workspace-write
144-
/cost
145-
/compact
146-
/memory
147-
/config
148-
/init
149-
/diff
150-
/version
151-
/export notes.txt
152-
/sessions
153-
/session list
154-
/exit
118+
rust/
119+
├── Cargo.toml # Workspace root
120+
├── Cargo.lock
121+
└── crates/
122+
├── api/ # Anthropic API client + SSE streaming
123+
├── commands/ # Shared slash-command registry
124+
├── compat-harness/ # TS manifest extraction harness
125+
├── runtime/ # Session, config, permissions, MCP, prompts
126+
├── rusty-claude-cli/ # Main CLI binary (`claw`)
127+
└── tools/ # Built-in tool implementations
155128
```
156129

157-
### 3) Resume an existing session
130+
### Crate Responsibilities
158131

159-
Inspect or maintain a saved session file without entering the REPL:
132+
- **api** — HTTP client, SSE stream parser, request/response types, auth (API key + OAuth bearer)
133+
- **commands** — Slash command definitions and help text generation
134+
- **compat-harness** — Extracts tool/prompt manifests from upstream TS source
135+
- **runtime** — `ConversationRuntime` agentic loop, `ConfigLoader` hierarchy, `Session` persistence, permission policy, MCP client, system prompt assembly, usage tracking
136+
- **rusty-claude-cli** — REPL, one-shot prompt, streaming display, tool call rendering, CLI argument parsing
137+
- **tools** — Tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, REPL runtimes
160138

161-
```bash
162-
cd rust
163-
cargo run -p rusty-claude-cli -- --resume session-123456 /status /compact /cost
164-
```
139+
## Stats
165140

166-
You can also inspect memory/config state for a restored session:
141+
- **~20K lines** of Rust
142+
- **6 crates** in workspace
143+
- **Binary name:** `claw`
144+
- **Default model:** `claude-opus-4-6`
145+
- **Default permissions:** `danger-full-access`
167146

168-
```bash
169-
cd rust
170-
cargo run -p rusty-claude-cli -- --resume ~/.claude/sessions/session-123456.json /memory /config
171-
```
147+
## License
172148

173-
## Available commands
174-
175-
### Top-level CLI commands
176-
177-
- `prompt <text...>` — run one prompt non-interactively
178-
- `--resume <session-id-or-path> [/commands...]` — inspect or maintain a saved session stored under `~/.claude/sessions/`
179-
- `dump-manifests` — print extracted upstream manifest counts
180-
- `bootstrap-plan` — print the current bootstrap skeleton
181-
- `system-prompt [--cwd PATH] [--date YYYY-MM-DD]` — render the synthesized system prompt
182-
- `self-update` — update the installed binary from the latest GitHub release when a matching asset is available
183-
- `--help` / `-h` — show CLI help
184-
- `--version` / `-V` — print the CLI version and build info locally (no API call)
185-
- `--output-format text|json` — choose non-interactive prompt output rendering
186-
- `--allowedTools <tool[,tool...]>` — restrict enabled tools for interactive sessions and prompt-mode tool use
187-
188-
### Interactive slash commands
189-
190-
- `/help` — show command help
191-
- `/status` — show current session status
192-
- `/compact` — compact local session history
193-
- `/model [model]` — inspect or switch the active model
194-
- `/permissions [read-only|workspace-write|danger-full-access]` — inspect or switch permissions
195-
- `/clear [--confirm]` — clear the current local session
196-
- `/cost` — show token usage totals
197-
- `/resume <session-id-or-path>` — load a saved session into the REPL
198-
- `/config [env|hooks|model]` — inspect discovered Claude config
199-
- `/memory` — inspect loaded instruction memory files
200-
- `/init` — bootstrap `.claude.json`, `.claude/`, `CLAUDE.md`, and local ignore rules
201-
- `/diff` — show the current git diff for the workspace
202-
- `/version` — print version and build metadata locally
203-
- `/export [file]` — export the current conversation transcript
204-
- `/sessions` — list recent managed local sessions from `~/.claude/sessions/`
205-
- `/session [list|switch <session-id>]` — inspect or switch managed local sessions
206-
- `/exit` — leave the REPL
207-
208-
## Environment variables
209-
210-
### Anthropic/API
211-
212-
- `ANTHROPIC_API_KEY` — highest-precedence API credential
213-
- `ANTHROPIC_AUTH_TOKEN` — bearer-token override used when no API key is set
214-
- Persisted OAuth credentials in `~/.claude/credentials.json` — used when neither env var is set
215-
- `ANTHROPIC_BASE_URL` — override the Anthropic API base URL
216-
- `ANTHROPIC_MODEL` — default model used by selected live integration tests
217-
218-
### CLI/runtime
219-
220-
- `RUSTY_CLAUDE_PERMISSION_MODE` — default REPL permission mode (`read-only`, `workspace-write`, or `danger-full-access`)
221-
- `CLAUDE_CONFIG_HOME` — override Claude config discovery root
222-
- `CLAUDE_CODE_REMOTE` — enable remote-session bootstrap handling when supported
223-
- `CLAUDE_CODE_REMOTE_SESSION_ID` — remote session identifier when using remote mode
224-
- `CLAUDE_CODE_UPSTREAM` — override the upstream TS source path for compat-harness extraction
225-
- `CLAWD_WEB_SEARCH_BASE_URL` — override the built-in web search service endpoint used by tooling
226-
227-
## Notes
228-
229-
- `compat-harness` exists to compare the Rust port against the upstream TypeScript codebase and is intentionally excluded from the requested release test run.
230-
- The CLI currently focuses on a practical integrated workflow: prompt execution, REPL operation, session inspection/resume, config discovery, and tool/runtime plumbing.
149+
See repository root.

0 commit comments

Comments
 (0)