You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: rewrite README + purge history markers from architecture.md
README.md / README.zh-CN.md — structural pass, corrected all stale numbers
---------------------------------------------------------------------------
Verified against the current tree:
- 24 crates (was 17 — counted wrong)
- 46 built-in tools (was 49 — looked at an outdated list)
- 33 slash commands (was "(20+)")
- 3800+ tests (was 3900+ — exceeded actual count)
- ~129k LOC (was "110k+")
- 188 spinner verbs (was 187)
- Permission modes: Default / AcceptEdits / TrustProject / DontAsk /
Dangerously / Plan. README previously listed bypassPermissions and auto,
which do not exist in the codebase.
Condensed the separately-promoted "Multi-Agent Architecture", "File History
& Rewind", and "Context Compaction" sections into compact prose; kept one
paragraph each instead of three full sections.
Added sections that were missing:
- Insider env-only toggles block (CRAB_COORDINATOR_MODE,
CRAB_AUTO_DREAM) so users know the gates exist without polluting --help.
- Experimental cargo features list in the Build block (auto-dream,
proactive, mem-ranker).
Architecture diagram updated to show 24 crates across 4 layers.
architecture.md — current state only, all history narrative removed
-------------------------------------------------------------------
Scrubbed every "Phase X" / "v2.3" / "pre-Phase" / "moved here" / "deleted
in …" / "[P0]" / "[P1]" / "[P2]" / "[Refactored]" / "replaces placeholder
…" / "promoted from Layer 2" marker. The document now describes the code
as it is, not how it got here.
Rewrote the §6.11 `crates/agent/` crate layout with the actual module
tree. Fixed §11.3 Agent Reliability to describe the current reliability
subsystem (ErrorClassifier + RecoveryStrategy + file_history + summarizer),
not the deleted CircuitBreaker / GracefulDegradation / in-memory rollback.
Consolidated a handful of "Intra-crate expansions" / "layout notes" /
"directory structure" headers that were phrased as change-logs back into
present-tense descriptions of the current layout.
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) pioneered the agentic coding CLI -- an AI that doesn't just suggest code, but thinks, plans, and executes autonomously in your terminal.
25
25
26
-
**Crab Code** brings this experience to the open-source world, independently built from the ground up in Rust:
26
+
**Crab Code** brings that experience to the open-source world, independently built from the ground up in Rust:
27
27
28
28
-**Fully open source** -- Apache 2.0, no feature-gating, no black box
29
29
-**Rust-native performance** -- instant startup, minimal memory, no Node.js overhead
30
30
-**Model agnostic** -- Claude, GPT, DeepSeek, Qwen, Ollama, or any OpenAI-compatible API
-**Layer 2a — Swarm**(default topology): peer-to-peer `TeamMode::PeerToPeer`. No extra module — it is just the default usage pattern when no overlay is active.
119
-
-**Layer 2b — Coordinator Mode**(gated overlay via `CRAB_COORDINATOR_MODE=1`): the coordinator's tool registry is reduced to `{Agent, SendMessage, TaskStop}`, workers spawned through it lose `{TeamCreate, TeamDelete, SendMessage}`, and the coordinator's system prompt carries an anti-pattern guardrail ("understand before delegating"). Fully unit-tested.
106
+
-**Teams**— base infrastructure: `WorkerPool`, per-agent mailbox router, shared `TaskList`(`fd-lock` file-locked `claim_task` for cross-process teammates), spawner backends (in-process, tmux).
107
+
-**Swarm**— the default flat topology (`TeamMode::PeerToPeer`). No extra module — it's just how teammates cooperate when no overlay is active.
108
+
-**Coordinator Mode**— a star-topology overlay gated on `CRAB_COORDINATOR_MODE=1`. The coordinator's tool registry is reduced to `{Agent, SendMessage, TaskStop}`; workers it spawns lose `{TeamCreate, TeamDelete, SendMessage}`; the coordinator's system prompt carries an anti-pattern guardrail.
120
109
121
110
### File History & Rewind
122
111
123
-
Every user session gets its own snapshot store at `~/.crab/file-history/{session_id}/`. Designed to mirror Claude Code's `fileHistory.ts` / `/rewind` behavior: each file edit is recorded as `{path-hash}@v{version}`, capped at 100 snapshots per session with LRU eviction. The `/rewind [path]` slash command is wired in the REPL; tool-level `track_edit` hooks on Edit/Write/Notebook are a planned follow-up.
112
+
Every session snapshots file edits under `~/.crab/file-history/{session_id}/` (at most 100 per session, LRU-evicted). `/rewind [path]` restores a file to an earlier version. Tool-level `track_edit` hooks on `Edit` / `Write` / `Notebook` are a planned follow-up; the `file_history` primitive is already unit-tested.
113
+
114
+
### Permission System
124
115
125
-
### Context Compaction
116
+
6 modes aligned with Claude Code behaviour:
126
117
127
-
`/compact` explicitly, or automatic compaction when the conversation crosses 80% of the model's context window. A heuristic summarizer (no extra LLM call) extracts decisions, code changes, unresolved issues, and topics, then replaces the conversation history with a single summary message while preserving the system prompt, session id, and cost accumulator. Emits `Event::CompactStart` and `Event::CompactEnd` for UI observability.
118
+
-**default** — prompt for potentially dangerous operations
119
+
-**acceptEdits** — auto-approve file edits, still prompt for Bash
120
+
-**trust-project** — auto-approve in-project writes; out-of-project and dangerous ops still prompt
121
+
-**dontAsk** — auto-approve everything (no prompts)
122
+
-**dangerously** — auto-approve everything except `denied_tools` (use with care)
123
+
-**plan** — read-only planning mode; mutations require explicit plan approval
124
+
125
+
Plus tool-level filtering via `--allowedTools` / `--disallowedTools` with glob patterns (`Bash(git:*)`, `mcp__*`, `Edit`).
128
126
129
127
### Slash Commands (33)
130
128
131
-
REPL intercepts `/<letter>…`input and dispatches through `SlashCommandRegistry` before anything hits the LLM, so paths like `/tmp/foo` still pass through as prompts.
129
+
The REPL intercepts input matching `/<letter>…` and dispatches through `SlashCommandRegistry` before the prompt reaches the LLM, so paths like `/tmp/foo` still pass through as prompts.
-`auto-dream` — background memory-consolidation cycles. Mirrors CCB's `src/services/autoDream/`: three-gate scheduler (min hours, min sessions, lock file) and the CCB consolidation prompt template are ready; the forked-agent LLM runner is stubbed and lands in a follow-up. Env: `CRAB_AUTO_DREAM=1`, `CRAB_AUTO_DREAM_MIN_HOURS`, `CRAB_AUTO_DREAM_MIN_SESSIONS`.
167
-
-`proactive` — placeholder for CCB's `feature('PROACTIVE')` mini-agent. Compiles the module skeleton only; real implementation pending.
168
-
-`mem-ranker` — enable the ML-based memory ranker inside `crab-memory`.
- Claude Code feature alignment — remaining gaps include the `auto-dream` forked-agent runner, tool-level `track_edit` hooks on Edit / Write / Notebook, and the `proactive` mini-agent
265
263
- OS-level sandboxing (Landlock / Seatbelt / Windows Job Object)
0 commit comments