mirror of https://github.com/instructkr/claw-code.git synced 2026-08-25 00:00:38 +08:00

Files

T

YeonGyu-Kim 08106b0c37 docs: add hierarchical AGENTS.md knowledge base

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

2026-08-16 15:18:33 +09:00

3.6 KiB

Raw Blame History

AGENTS.md — rusty-claude-cli (the `claw` binary)

OVERVIEW

Crate rusty-claude-cli produces the claw binary (~25 subcommands). Wires together api, runtime, tools, commands, plugins; terminal via crossterm/rustyline/syntect. Hand-rolled arg parser (no clap).

main.rs MAP

src/main.rs is ~19,800 lines. Landmark table:

Lines	Section
73–330	Provenance/model types (`ModelSource`, `ModelProvenance`, `PermissionModeSource`), build constants
330–682	Error taxonomy (`classify_error_kind`, JSON/text error output)
774–994	Global flags, `--cwd`/`-C` stripping, stdin plumbing
995–1158	`run()`: single flat match dispatching `CliAction` variants
1162–1280	`CliAction` enum, 25 struct variants (each carries `output_format`)
1312–1477	Output-format machinery: `OnceLock` statics, duplicate-flag tracking
1478–2272	`parse_args`: ~800-line manual token loop
2542–3389	Per-subcommand sub-parsers inside `parse_args`
2902–3389	Model/permission/allowed-tools resolution
3390–4696	Doctor subsystem (~13 `check_*_health` fns)
4697–6062	Manifests, bootstrap-plan, system-prompt, version, `resume_session`
5459–7047	`StatusContext`, `BinaryProvenance`, broad-cwd policy, stale-base preflight
7048–9423	`run_repl` interactive loop (`LiveCli` struct, streaming, heartbeat, `HookAbortMonitor`)
9424–14264	Snapshot printers: session-list, status, sandbox, models, help topics, acp, `run_init` (L11027), `run_export` (L11715), `print_help` (L14055)
14266–19831	In-file `mod tests` + 3 smaller test modules (one embeds a Python MCP fixture)

CONVENTIONS

Every subcommand supports --output-format text|json, env-overridable.
raw_args_request_json_output pre-scans argv before parsing to suppress stderr config warnings in JSON mode.
Dual renderers for each output path: human text + structured *_json.
Unknown flags/typos get levenshtein-distance suggestions.
Comments carry issue numbers (#824, #146, etc.) when tracking known problems.
main() (L330) is only the error envelope. All real work happens in run().
Error output always includes status, error_kind, action, hint, exit_code fields.
classify_error_kind maps message prefixes to snake_case kind tokens.
JSON errors go to stdout, text errors to stderr.
Sibling modules: init.rs, input.rs (rustyline), render.rs (MarkdownStreamState, Spinner, syntect), setup_wizard.rs.
build.rs injects GIT_SHA, RUSTC_VERSION, GIT_DIRTY via cargo:rustc-env.

ANTI-PATTERNS

File opens with crate-wide #![allow(...)] suppressing 13 lints including dead_code and unused_imports. Legacy. Do NOT extend this list.
9+ functions carry #[allow(clippy::too_many_lines)]. Tolerated, not license for more.
Package/bin name mismatch: crate is rusty-claude-cli, binary is claw. Watch for this in paths and test macros.

TESTS

All tests live in tests/ (6 files), black-box style. They spawn env!("CARGO_BIN_EXE_claw") in unique temp dirs (AtomicU64 counter).

File	What it covers
`output_format_contract.rs`	~105 tests pinning `kind`/`status`/`action` JSON contract for EVERY subcommand. Must update when adding/changing any command output. 5,986 lines.
`resume_slash_commands.rs`	Resume and slash-command behavior
`cli_flags_and_config_defaults.rs`	Flag parsing, config file defaults
`compact_output.rs`	Compact output mode
`compact_repl_panic.rs`	Nested-runtime panic regression
`mock_parity_harness.rs`	Scenario-driven tests against mock-anthropic-service, driven by `rust/mock_parity_scenarios.json`

3.6 KiB Raw Blame History Unescape Escape

AGENTS.md — rusty-claude-cli (the claw binary)