PROJECT KNOWLEDGE BASE

Generated: 2026-08-16 Commit: b71afdd Branch: main

OVERVIEW

Claw Code: public Rust implementation of the claw CLI agent harness (Claude-Code-style). Canonical code lives in rust/; the repo is an agent-managed exhibit (harnesses plan/execute/verify per README), not a hand-operated product. src/ is a companion Python porting/parity workspace, not production code.

STRUCTURE

claw-code/
├── rust/      # canonical Cargo workspace: 11 crates, `claw` binary
├── src/       # Python porting workspace + reference_data/ parity snapshots
├── tests/     # Python unittest validation of src/ + scripts/ (stdlib unittest)
├── docs/      # g0XX gate verification maps + topic docs
├── scripts/   # fmt.sh, dogfood-build.sh, roadmap/board helpers
├── assets/    # README images only
└── install.sh, Containerfile, docker-compose.yml

WHERE TO LOOK

CODE MAP

(Refs = rg count across rust/crates; rust-analyzer references timed out during mapping.)

CONVENTIONS

• unsafe_code = "forbid" workspace-wide; every crate opts in via [lints] workspace = true; clippy all=warn, pedantic=allow
• Edition 2021, resolver 2, publish=false; no rust-toolchain pin (CI floats stable); no rustfmt.toml/clippy.toml — stock defaults
• Giant flat files by design (main.rs 19.8k, tools/lib.rs 10.9k, commands/lib.rs 7.2k): organization is positional — types → spec table → dispatch → handlers → tests at EOF
• Dual output paths everywhere: render_x + render_x_json; JSON errors to stdout, text errors to stderr
• Tests: inline #[cfg(test)] mod tests primary; integration tests spawn CARGO_BIN_EXE_claw subprocess against mock-anthropic-service; tempfile everywhere; env-mutating tests serialize via env_lock/test_env_lock
• Comments carry issue numbers (#824, #146); gate tests named by roadmap gate (g004_conformance.rs)
• Python side: stdlib only, python -m unittest; src/ mixes camelCase (QueryEngine.py) and snake_case filenames

ANTI-PATTERNS (THIS PROJECT)

• NEVER cargo install claw-code — crates.io stub is deprecated and installs claw-code-deprecated.exe; build from source
• Forbidden doc strings (CI-enforced by .github/scripts/check_doc_source_of_truth.py): old org links github.com/Yeachan-Heo/claw-code, github.com/code-yeongyu/claw-code, discord.gg/6ztZB9jvWq, assets/clawd-hero.jpeg
• Deprecated config keys: permissionMode → permissions.defaultMode; enabledPlugins → plugins.enabled; env RUSTY_CLAUDE_PERMISSION_MODE is dead
• Direct push to main is policy-blocked (main_push_forbidden approval scope)
• Automation lanes must not merge/close remote PRs/issues (docs/anti-slop-triage.md)
• claw init must not scaffold dontAsk permission mode (regression-pinned in output_format_contract.rs)
• File-level #![allow(dead_code)] blocks (main.rs, session_control.rs) are tolerated legacy — do not extend the pattern

UNIQUE STYLES

• Dogfood build: scripts/dogfood-build.sh injects GIT_SHA; claw version provenance must equal HEAD
• Mock parity: rust/mock_parity_scenarios.json drives CLI subprocess vs MockAnthropicService
• Dogfooding uses CLAW_CONFIG_HOME=$(mktemp -d) for config isolation
• Env contracts: GIT_SHA (build), CLAW_CONFIG_HOME (config dir), OLLAMA_HOST (provider override), *_API_KEY/*_BASE_URL per provider

COMMANDS

scripts/fmt.sh --check                 # fmt check (apply: scripts/fmt.sh)
cd rust && cargo clippy --workspace --all-targets -- -D warnings
cd rust && cargo test --workspace
cd rust && cargo build -p rusty-claude-cli   # binary: rust/target/debug/claw
python -m unittest discover -s tests   # Python suite
python .github/scripts/check_doc_source_of_truth.py && scripts/roadmap-check-ids.sh   # docs/roadmap CI

NOTES

• claw binary comes from crate rusty-claude-cli (package/bin name mismatch)
• rust-ci.yml triggers only on rust/, docs/, listed meta file changes (path filters)
• CI clippy job runs without -D warnings — weaker than the documented gate; known pre-existing failures recorded in docs/g002/g003 maps
• claw acp is a status stub, not a real ACP server
• rust/ has committed harness dotdirs (.clawd-agents/, .omc/, .sandbox-home/) — intentional