Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (81 loc) · 6.17 KB

AGENTS.md

File metadata and controls

92 lines (81 loc) · 6.17 KB
Raw

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

Task Location Notes
CLI subcommands rust/crates/rusty-claude-cli/src/main.rs hand-rolled parser; CliAction enum ~L1162; dispatch in run() L995-1158
Sessions/permissions/MCP rust/crates/runtime/src/ 47 flat modules
Provider clients rust/crates/api/src/providers/ anthropic.rs + openai_compat.rs
Tool definitions rust/crates/tools/src/lib.rs 55-tool spec table L484-1348
Slash commands rust/crates/commands/src/lib.rs 120+ spec table L60-1047
Plugins/hooks rust/crates/plugins/src/ manifest = .claude-plugin/plugin.json
Lean agent harness rust/crates/claw-analog/src/lib.rs lib+bin; tool loop over api+runtime
RAG HTTP service rust/crates/claw-rag-service/src/ axum; SQLite + optional Qdrant
Test mock server rust/crates/mock-anthropic-service/ SCENARIO_PREFIX scripted responses
Python porting CLI src/main.py argparse: manifest, parity-audit, graphs
Parity reference DB src/reference_data/subsystems/ 29 JSON snapshots of TS archive

CODE MAP

Symbol Type Location Refs Role
Session struct runtime/src/session.rs:117 229 session persistence/lifecycle
ConfigLoader struct runtime/src/config.rs:409 83 config schema/load
PluginManager struct plugins/src/lib.rs 48 plugin install/registry
PermissionEnforcer struct runtime/src/permission_enforcer.rs:27 35 pre-dispatch permission gate
ConversationRuntime struct runtime/src/conversation.rs:130 32 conversation loop driver
McpServerManager struct runtime/src/mcp_stdio.rs:488 30 MCP JSON-RPC processes
HookRunner struct runtime/src/hooks.rs:155 25 shell hook execution
CliAction enum rusty-claude-cli/src/main.rs:1162 — 25 subcommand variants
mvp_tool_specs fn tools/src/lib.rs:484 — static 55-tool table
SLASH_COMMAND_SPECS const commands/src/lib.rs:60 — 120+ slash commands

(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