mirror of
https://github.com/instructkr/claw-code.git
synced 2026-08-25 00:00:38 +08:00
YeonGyu-Kim
08106b0c37
Root knowledge base plus complexity-scored subdirectory files for the rust/ workspace, its five highest-mass crates (runtime, rusty-claude-cli, api, tools, commands, plugins), and the src/ Python porting workspace. Generated via init-deep: 13 parallel explore agents, LSP/ast-grep code map, centrality-scored placement. Snapshot in .omo/init-deep.json (local).
93 lines
6.2 KiB
Markdown
93 lines
6.2 KiB
Markdown
# 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
|
|
```bash
|
|
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
|