# https://github.com/PDgit12/knitbrain Project Manual

Generated at: 2026-06-23 18:44:12 UTC

## Table of Contents

- [Overview & System Architecture](#page-1)
- [Context Compression, Recall Store & Proxy](#page-2)
- [Memory, Knowledge Graph & Engine Internals](#page-3)
- [CLI Commands, Platform Integration, Hooks, Hub & Operations](#page-4)

<a id='page-1'></a>

## Overview & System Architecture

### Related Pages

Related topics: [Context Compression, Recall Store & Proxy](#page-2), [Memory, Knowledge Graph & Engine Internals](#page-3), [CLI Commands, Platform Integration, Hooks, Hub & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)
- [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)
- [CLAUDE.md](https://github.com/PDgit12/knitbrain/blob/main/CLAUDE.md)
- [src/engine/agents.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/agents.ts)
- [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts)
- [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)
- [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)
- [src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts)
- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)
- [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)
- [tsconfig.build.json](https://github.com/PDgit12/knitbrain/blob/main/tsconfig.build.json)
</details>

# Overview & System Architecture

## Purpose and Design Philosophy

knitbrain is the **local-first brain for coding agents**, delivered as an MCP server that exposes 27 tools to any MCP-compatible host (Claude Code, Cursor, Codex, Copilot, Windsurf, Cline, and others). It collapses three concerns most tools split apart into a single substrate: lossless context compression, per-project memory, and tier-routed workflow — plus an autonomous loop that drives the whole stack across fresh contexts. Source: [README.md:11-22]()

The package's description is explicit about its published numbers: "~48% of all tool-result tokens on real sessions (60–70% on code/JSON/logs), answer-preservation gated, reproducible with one command". Source: [package.json:3-5]() Honesty matters here — bench reports an **all-inclusive** average, counting every tool-result token including the small outputs that pass through uncompressed, rather than cherry-picked best-case fixtures. Source: [README.md:25-31]() The bench harness enforces that policy with a real-shape suite (fixtures statistically shaped like 3.3M profiled real tokens) whose per-shape floors sit a safety margin **below** the measured corpus — a regression in any real shape fails the build. Source: [scripts/bench.ts:9-24]()

The latest 0.4.4 release is a small but high-impact fix: `knitbrain_read` now accepts absolute paths (what hosts like Claude Code actually pass), removing a previous refusal that caused user-scoped installs to fall back to raw Read. Source: [src/mcp/tools.ts:30-43]() The release ships with 277 tests and green CI.

## System Architecture

The system has three concentric layers: a host-facing MCP tool surface, a deterministic core (engine + optimizer), and persistent state (recall store, memory, knowledge graph, generated agent files).

```mermaid
graph TB
  subgraph Host["MCP Host — Claude Code / Cursor / Codex / Copilot / ..."]
    HA[Host Agent]
  end

  subgraph MCP["MCP Server: knitbrain (Node, ≥18, 3 deps)"]
    TD[Tool Dispatcher<br/>27 tools]
    EL[Engine Layer<br/>workflow · memory · agents]
    OL[Optimizer Layer<br/>router + handlers]
    PR[Proxy / Cache Aligner<br/>optional API-key path]
  end

  subgraph State["Persistent Local State"]
    CCR[CCR Recall Store<br/>content-addressed]
    LF[learnings.json + handoff.txt]
    KG[Imports / Exports / Dependents]
    AG[.claude/agents/*.md]
  end

  HA <-->|tool calls| TD
  TD -->|"data" output| OL
  TD -->|"verbatim" output| EL
  OL -->|skeleton + ⟨recall:hash⟩| TD
  OL -->|original| CCR
  TD -->|reads/writes| LF
  TD -->|reads| KG
  TD -->|writes| AG
  EL -->|classify| WT[Tier Router]
  PR -->|compress + align| HA
```

## Core Subsystems

**Optimizer (`src/optimizer/`)** — Lossless compression via deterministic content-type detection (`json`, `diff`, `search`, `log`, `code`, `prose`, `text`) and per-shape handlers. Structured shapes outrank the looser code heuristic so test logs and grep dumps compress correctly. Source: [src/optimizer/router.ts:55-63](), [src/optimizer/types.ts:3-13]() The router never expands output: if compression isn't meaningfully smaller, the original passes through untouched, and a `⟨recall:hash⟩` handle always round-trips byte-for-byte. A declaration-rescue pass re-appends any top-level signature that body elision dropped, so the API surface an agent navigates by never vanishes from the skeleton. Source: [src/optimizer/router.ts:23-34]()

**Engine (`src/engine/`)** — Tier-routed workflow. A deterministic classifier (no ML) sizes each task into `inquiry` → `trivial` → `standard` → `complex`, with keyword patterns for `COMPLEX` (architect/refactor/migrate/security/schema) and `INQUIRY` (wh-question / trailing `?`). Source: [src/engine/workflow.ts:9-17]() A self-healing false-positive loop tracks when claimed ≠ actual and shifts the file-count bar for "complex" (`scopeAdjust`). Source: [src/engine/workflow.ts:21-27]() Memory is per-project, file-backed, and outcome-ranked: a learning reported wrong is discredited and sinks. Source: [src/engine/memory.ts:39-50]() Domain agents are auto-proposed by grouping the knowledge graph by directory and capped at 4 per complex task, with a slug-safe writer that can never escape `.claude/agents/`. Source: [src/engine/agents.ts:42-58]()

**MCP Tool Surface (`src/mcp/tools.ts`)** — Output discipline at the dispatch chokepoint: `"data"` results are auto-compressed (skeleton + handle, original in CCR); `"verbatim"` results (governance/protocol/control) pass through unmodified. Source: [src/mcp/tools.ts:52-66]()

**Proxy (`src/proxy/optimize-request.ts`)** — Optional loopback for API-key users (`knitbrain wrap claude`): compresses on the wire and **cache-aligns** the system prefix by whitespace-normalizing and moving volatile lines ("Today's date is …") to a marked tail, preserving content verbatim while stopping the leading bytes from churning between sessions. Source: [src/proxy/optimize-request.ts:24-44]()

## Configuration, Build & Distribution

Three binaries ship from a single package: `knitbrain` (CLI + MCP server), `knitbrain-proxy`, and `knitbrain-hook`. Source: [package.json:19-22]() The published surface is the compiled `dist/` tree; the build uses `tsconfig.build.json` to restrict compilation to `src/**` and exclude tests and scripts. Source: [tsconfig.build.json:1-9](), [package.json:9-18]()

The verify pipeline chains every gate: `typecheck → lint → test → build → consistency → bench` — a single command fails the build on any regression in real-shape compression, so the 48% headline number is enforced, not aspirational. Source: [package.json:39-46]()

Operational commands span profiling on real transcripts (`profile`, `evals`), loop workers (`loop`, `fan`), governance (`terse`, `compress`), and observability (`dashboard`, auto-detected by platform and plan from the MCP handshake). Source: [README.md:60-72]()

## See Also

- Compression Pipeline — handler-level internals for `json`, `code`, `log`, `diff`
- Workflow & Tier Routing — classifier rules, calibration loop, plan-mode gates
- Memory & Knowledge Graph — learnings ranking, handoff lifecycle, graph freshness
- MCP Tool Reference — full 27-tool catalog with input schemas and output kinds

---

<a id='page-2'></a>

## Context Compression, Recall Store & Proxy

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [Memory, Knowledge Graph & Engine Internals](#page-3), [CLI Commands, Platform Integration, Hooks, Hub & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)
- [src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts)
- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)
- [src/ccr/store.ts](https://github.com/PDgit12/knitbrain/blob/main/src/ccr/store.ts)
- [src/measure.ts](https://github.com/PDgit12/knitbrain/blob/main/src/measure.ts)
- [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)
- [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)
- [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)
</details>

# Context Compression, Recall Store & Proxy

## Purpose and Scope

Context compression is the central token-savings lever in knitbrain. It operates on tool-result payloads — the output of `Read`, `Bash`, `Grep`, and similar host tools — and turns them into a smaller "skeleton" view while keeping the exact original reachable through a content-addressed handle. According to [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md), the project reports ~46% savings over ~3M real tool-result tokens and ~55% when counting only blocks ≥ 400 tokens. The subsystem has three coordinated pieces: a **router + handlers** that decides what to elide ([src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)), a **CCR (Content-Addressed Recall) store** that holds originals for byte-exact recovery ([src/ccr/store.ts](https://github.com/PDgit12/knitbrain/blob/main/src/ccr/store.ts)), and an optional **wire-level proxy** that compresses requests on the network path for API-key users ([src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)).

The 0.4.4 release tightened the integration with hosts: `knitbrain_read` now accepts absolute paths so the tool is a true drop-in for the host's raw `Read` ([package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json), [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)).

## Content-Type Detection and the Router

The router is a deterministic classifier — no ML, no heuristics that depend on the caller. `detect()` in [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts) walks a fixed priority order: `json` → `diff` → `search` → `log` → `code` → `text`. The structured shapes (diff/search/log) are checked before the looser code heuristic because "grep dumps and test logs used to trip `isCode` and compress poorly" ([src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)). The `ContentType` union is defined in [src/optimizer/types.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/types.ts); notably `prose` is **produced**, not detected — it is the output of the sentence-anchor path for short prose, and it gets its own TOIN kind so over-retrieval backs it off independently.

```mermaid
flowchart LR
    A[Tool result text] --> B{detect}
    B -->|json| J[json handler]
    B -->|diff| D[diff handler]
    B -->|search| S[search handler]
    B -->|log| L[log handler]
    B -->|code| C[code handler<br/>tree-sitter AST + anchors]
    B -->|text| T[text handler<br/>sentence anchors]
    J --> R[skeleton + ⟨recall:hash⟩]
    D --> R
    S --> R
    L --> R
    C --> R
    T --> R
    R -->|CCR store| CCR[(original bytes)]
    R --> O[agent context]
    O -.->|knitbrain_retrieve| CCR
```

Three guardrails keep compression safe. First, a **declaration rescue** (`rescueDecls` in [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)) re-appends any top-level signature that body-elision dropped — concatenated multi-file dumps can let one function's brace range over-run and swallow later signatures, and the API surface an agent navigates by must never vanish. Second, a **never-expand guard** short-circuits to the original whenever `savedPct < PARAMS.minSavingPct`, so small payloads pass through untouched rather than growing. Third, an **anchor path** is tried for code after the AST pass; whichever produces the smaller skeleton wins ([src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)).

## The Recall Store (CCR) and MCP Surface

Compression is only useful if the original is recoverable. The CCR store is a content-addressed map keyed by a hash that appears in the skeleton as `⟨recall:hash⟩`. A agent that needs the exact bytes calls `knitbrain_retrieve` with the handle; the tool strips the angle brackets, accepts the legacy `ccr:` prefix, and returns the original verbatim ([src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)). The retrieval is also a **TOIN feedback signal** — `ctx.feedback.onRetrieve(handle)` records a vote that the skeleton wasn't enough, and over time the system self-tunes the threshold for that content kind.

The MCP surface enforces an output discipline at the dispatch chokepoint: tools marked `output: "data"` are auto-compressed (skeleton + handle, original stored in CCR), while tools marked `output: "verbatim"` are returned exactly as-is because they carry governance or protocol text the agent must read literally ([src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)). The same file defines `knitbrain_read`, the file-reading tool that the 0.4.4 release fixed. The previous implementation resolved paths against the MCP server's cwd and refused anything outside it, so user-scoped installs fell back to the host's raw `Read` and the skeleton was never used. The current implementation uses `isAbsolute` to accept absolute paths directly and `resolve(process.cwd(), …)` for relative ones, with the comment noting that the agent already has full file read via the host, so scoping there adds no security — it only broke the drop-in use case ([src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)).

The compression regression gate is `scripts/bench.ts`, which runs two suites against the real shape distribution of 3.3M tool-result tokens (code 47%, repetitive logs 17%, short prose 16%, long prose 7%, test output 6%, JSON 5%, diffs 1%) and asserts per-shape floors and byte-for-byte round-trip fidelity ([scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)). Numbers from a best-case synthetic suite are explicitly **not** quoted as real-world savings.

## The Wire-Level Proxy (API-Key Path)

For users with an API key — Claude, OpenAI, or compatible providers — the optional loopback proxy sits between the agent and the model API and compresses the **request** body on the wire in addition to tool-result compression. According to [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md), on a subscription the wire path cannot apply (OAuth traffic cannot be intercepted), but the main lever — tool-result compression — runs identically either way, so no API key is required to benefit from the system.

`optimize-request.ts` ([src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)) walks the message array and runs each piece of content through the compressor. A separate **cache-aligner** stabilizes the system prefix: it whitespace-normalizes the system prompt and moves volatile lines (e.g. "Today's date is …") to a marked tail section, preserving content verbatim while stopping the leading bytes from churning between sessions. The OpenAI protocol is handled explicitly because its system prompt is the leading `system` / `developer` message, not a top-level `system` field.

## Failure Modes and Operational Notes

- **Compression that doesn't shrink.** A payload below `PARAMS.minSavingPct` passes through unchanged; this is intentional and prevents the optimizer from making small outputs larger.
- **Lost declarations in multi-file dumps.** The declaration rescue is the only path that re-surfaces signatures the body-elision dropped; without it, AST/heuristic/anchor paths can each swallow later top-level declarations.
- **Lost host integration on user-scoped installs.** Before 0.4.4, `knitbrain_read` refused paths outside the MCP server's cwd, forcing a fallback to the host's raw `Read` and bypassing the optimizer entirely. Absolute-path acceptance is the fix.
- **Over-retrieval.** A skeleton that an agent keeps expanding back to the original feeds TOIN feedback; the per-kind rate eventually backs off that handler ([src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)).
- **Wire compression on OAuth.** The proxy path only applies to API-key traffic; subscription/OAuth sessions still get tool-result compression but not on-the-wire request shrinking ([README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)).

## See Also

- [Tools & MCP Surface](tools-mcp-surface.md) — the 27 MCP tools that expose compression
- [Memory, Knowledge Graph & Handoff](memory-knowledge-handoff.md) — per-project state on top of compressed context
- [Tier-Routed Workflow](tier-routed-workflow.md) — how `inquiry → trivial → standard → complex` shapes the work that produces and consumes these payloads

---

<a id='page-3'></a>

## Memory, Knowledge Graph & Engine Internals

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [Context Compression, Recall Store & Proxy](#page-2), [CLI Commands, Platform Integration, Hooks, Hub & Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/engine/memory.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/memory.ts)
- [src/engine/knowledge.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/knowledge.ts)
- [src/engine/workflow.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/workflow.ts)
- [src/engine/agents.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/agents.ts)
- [src/engine/calibration.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/calibration.ts)
- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [src/optimizer/router.ts](https://github.com/PDgit12/knitbrain/blob/main/src/optimizer/router.ts)
- [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)
- [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)
- [CLAUDE.md](https://github.com/PDgit12/knitbrain/blob/main/CLAUDE.md)
</details>

# Memory, Knowledge Graph & Engine Internals

## Overview

The knitbrain engine is the local, file-backed substrate that powers every MCP tool exposed to a coding agent. It is fully deterministic (no ML runtime, no network) and is shared by compression, workflow routing, agent spawning, and the live dashboard. Every engine component implements a small, narrowly-scoped interface that is composed through the `ToolContext` injected at the MCP dispatch chokepoint. Source: [src/mcp/tools.ts:18-30]().

The engine divides cleanly into three concerns:

- **Per-project memory** — learnings, handoffs, headline ranking.
- **Knowledge graph** — imports/exports/dependents built from project source.
- **Workflow + classification** — deterministic tier routing with a self-healing false-positive loop, plus the supporting stores (`feedback`, `calibration`, `meter`, `skills`, `teams`, `activity`).

Per the release notes shipped in v0.4.4, even the file-reading side of the engine was relaxed so that `knitbrain_read` now accepts absolute paths — the same engines still back it, only the path resolution rule changed.

## Memory Subsystem

`createMemory(root)` returns a file-backed `Memory` store persisted under `learnings.json` and `handoff.txt`. It exposes three primitives: `recordLearning`, `queryLearnings`, and `handoff`. Source: [src/engine/memory.ts:46-118]().

Learnings are ranked by outcome: each record carries `helpful` and `unhelpful` counters, and a learning reported wrong is discredited and sinks. Dedup is a substring match on the summary, so re-recording a near-duplicate updates counts instead of duplicating rows. A forward-migration step in `load()` backfills `helpful`/`unhelpful` on records written before the signal fields existed. Source: [src/engine/memory.ts:53-66]().

Session handoffs auto-clear when stale, and the headline list (`topLearnings`) is recomputed on every query so the agent always sees the current ranking — never a cached snapshot. Source: [src/engine/memory.ts:88-101]().

## Knowledge Graph

`createKnowledge(projectRoot, cacheDir)` builds a regex-based, dependency-free import/export graph for TS/JS projects and persists it to `cache.json`. A reverse adjacency index (`dependents`) is rebuilt alongside the graph so `queryDependents` is an O(1) lookup. Source: [src/engine/knowledge.ts:18-44]().

Two reliability invariants are enforced at load time:

1. **Ghost-pruning** — cached nodes for files deleted since the last scan are dropped, so a stale cache never reports a non-existent file.
2. **Deterministic re-scan** — file-system walks skip dot-dirs and a `SKIP_DIRS` allowlist, then group by directory for downstream `proposeAgents` consumption. Source: [src/engine/knowledge.ts:50-72]().

The graph is queried through three MCP tools — `knitbrain_query_imports`, `knitbrain_query_exports`, and `knitbrain_query_dependents` — all routed through the dispatcher with `output: "data"` so results are skeletonized and recall-handled. Source: [src/mcp/tools.ts:174-218]().

## Workflow Tier Classifier

The classifier is a pure function: `classifyTask(description, files, scopeAdjust) → Classification`. There are four tiers — `inquiry`, `trivial`, `standard`, `complex` — selected by regex over the description and a file-count threshold adjusted by calibration. Source: [src/engine/workflow.ts:1-12]().

Keyword rules carry the obvious semantics: `INQUIRY` matches question-shaped prompts, `TRIVIAL` matches one-line fixes (`typo`, `rename`, `lint`, `whitespace`, `format`, `one-line`), and `COMPLEX` matches risk words (`architect`, `refactor`, `migrat`, `schema`, `security`, `breaking`, `protocol`, `concurren`). Source: [src/engine/workflow.ts:14-17]().

| Tier | Trigger | Response |
|---|---|---|
| Inquiry | Question shape, 0 files | Just answer |
| Trivial | Trivial keyword + small scope | Execute → verify |
| Standard | Mid-scope fix | Research → execute → review |
| Complex | ≥4 files OR risk keyword OR plan-mode flag | Full 6-phase loop with auto plan-mode |

Source: [src/engine/workflow.ts:18-44]().

The `scopeAdjust` parameter is the dial turned by the false-positive calibration loop. When an agent calls `knitbrain_record_false_positive({claimed_tier, actual_tier})`, the calibration store shifts the file-count bar for `complex` and the next classification reflects the new bar without restart. Keyword-triggered `complex` is exempt unless the bar was raised — explicit risk words stay authoritative until users vote otherwise. Source: [src/mcp/tools.ts:230-247]().

## Supporting Engines

The remaining engines are small and serve one purpose each, all composed through `ToolContext`:

- **Feedback** — drives the `TOIN` self-tuning signal: every retrieval that returns the original is a vote that a skeleton wasn't enough, and every miss signals compression overreach. The router uses this to decide whether to skip the prose handler on subsequent calls. Source: [src/mcp/tools.ts:142-156]().
- **Calibration** — owns `recordFalsePositive` and the `scopeAdjust` returned to `classifyTask`. Pending counters (`fpDirections`) accumulate until a threshold (3) is hit, then the bar shifts. Source: [src/mcp/tools.ts:230-247]().
- **Skills** — provides telegraphic skill bodies used as mission briefs for cold sub-agents; non-empty `constraints` are injected into generated agent specs verbatim. Source: [src/engine/agents.ts:42-58]().
- **Teams** — `TeamBoard.post(author, summary)` is the single posting primitive used for agent creation events and hub mirroring. Source: [src/mcp/tools.ts:60-72]().
- **Meter** — measures knitbrain's own throughput per agent connection; works on every MCP client because it counts what knitbrain produced, not what the host exposed. Source: [src/mcp/tools.ts:18-30]().
- **Activity** — optional per-connection CRM feed surfaced on the live dashboard. Source: [src/mcp/tools.ts:30-34]().

## Compression Router (Engine Boundary)

The router is the engine's data-side boundary. `detect(text)` classifies content deterministically (`json` → `diff` → `search` → `log` → `code` → `text`), and structured shapes outrank looser heuristics so grep dumps and test logs stop tripping the code path. Source: [src/optimizer/router.ts:64-78]().

`rescueDecls(original, skeleton)` re-surfaces any top-level declaration that body-elision accidentally dropped — concatenated multi-file dumps can let one function body's brace range swallow later signatures, and the API surface an agent navigates by must never vanish from the skeleton. Source: [src/optimizer/router.ts:42-54]().

The benchmark harness in `scripts/bench.ts` runs two suites — a **real-shape** suite sized to the profiled distribution of 3.3M real tool-result tokens (with per-shape floors a safety margin below measured real numbers) and a **best-case** synthetic suite that catches handler-ceiling regressions only. Fidelity is asserted too: error lines and result summaries must survive byte-for-byte, and every output must round-trip via `⟨recall:hash⟩`. Source: [scripts/bench.ts:1-22]().

## Failure Modes

- **Stale graph cache** → ghost-prune drops deleted files on next load; a corrupt cache triggers a transparent rebuild. Source: [src/engine/knowledge.ts:38-46]().
- **Classifier over-routes to complex** → false-positive loop shifts the bar after 3 votes; keyword triggers remain authoritative. Source: [src/engine/workflow.ts:7-12]().
- **Absolute path passed to `knitbrain_read`** → in v0.4.4 this now resolves correctly via `isAbsolute` + `resolve(process.cwd(), requested)`; older versions refused anything outside `cwd`, forcing user-scoped installs back to raw Read. Source: [src/mcp/tools.ts:178-186]().

## See Also

- [knitbrain README — Loop engineering, Commands, The numbers](https://github.com/PDgit12/knitbrain/blob/main/README.md)
- [CLAUDE.md — Tier vocabulary and domain architecture](https://github.com/PDgit12/knitbrain/blob/main/CLAUDE.md)
- [package.json — engines, bin entries, exports](https://github.com/PDgit12/knitbrain/blob/main/package.json)

---

<a id='page-4'></a>

## CLI Commands, Platform Integration, Hooks, Hub & Operations

### Related Pages

Related topics: [Overview & System Architecture](#page-1), [Context Compression, Recall Store & Proxy](#page-2), [Memory, Knowledge Graph & Engine Internals](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/setup.ts](https://github.com/PDgit12/knitbrain/blob/main/src/setup.ts)
- [src/platforms.ts](https://github.com/PDgit12/knitbrain/blob/main/src/platforms.ts)
- [src/global-config.ts](https://github.com/PDgit12/knitbrain/blob/main/src/global-config.ts)
- [src/hooks/index.ts](https://github.com/PDgit12/knitbrain/blob/main/src/hooks/index.ts)
- [src/hooks/pretooluse.ts](https://github.com/PDgit12/knitbrain/blob/main/src/hooks/pretooluse.ts)
- [src/hooks/sessionstart.ts](https://github.com/PDgit12/knitbrain/blob/main/src/hooks/sessionstart.ts)
- [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md)
- [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)
- [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)
- [src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts)
- [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts)
- [src/engine/agents.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/agents.ts)
</details>

# CLI Commands, Platform Integration, Hooks, Hub & Operations

This page covers the operational surface of **knitbrain**: the user-facing CLI commands, how the server detects and wires into host editors, the hook system that sits in front of MCP tools, and the optional Hub used to mirror team activity between projects.

## CLI Command Surface

`knitbrain` is published as a single binary invoked from the command line. The `package.json` `bin` entry plus the scripts block in [package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json) define the entrypoints; the canonical user-facing commands are documented in [README.md](https://github.com/PDgit12/knitbrain/blob/main/README.md).

| Command | Purpose |
|---|---|
| `knitbrain setup` | Detect host platforms, write native MCP config + rules. |
| `knitbrain profile` | Measure compression savings on real transcripts. |
| `knitbrain evals` | Answer-preservation gates; exit non-zero on regression. |
| `knitbrain loop <goal>` | Autonomous single-worker loop over a checkbox goal file. |
| `knitbrain fan <goal>` | Parallel loop — N workers in isolated git worktrees. |
| `knitbrain compress <file>` | Terse-rewrite a memory file (keeps a backup). |
| `knitbrain terse [level]` | Print the terse-output guide (`lite`/`full`/`ultra`). |
| `knitbrain dashboard` | Live local dashboard (auto-detected platform + plan). |
| `knitbrain wrap claude` | Optional loopback proxy for API-key users. |

The verify pipeline used during development and pre-publish lives in the `verify` script: `typecheck && lint && test && build && consistency && bench` ([package.json](https://github.com/PDgit12/knitbrain/blob/main/package.json)). The compression regression gate that backs the `bench` step is [scripts/bench.ts](https://github.com/PDgit12/knitbrain/blob/main/scripts/bench.ts), which runs two suites — a real-shape suite statistically matching profiled tool-result distributions, and a best-case synthetic suite — and asserts per-shape floors below the measured real-corpus numbers.

## Platform Integration & Setup

`knitbrain setup` is the integration entrypoint. It calls `detectPlatforms` and then dispatches to per-platform artifact writers defined in [src/platforms.ts](https://github.com/PDgit12/knitbrain/blob/main/src/platforms.ts). The flow is:

```mermaid
flowchart LR
    A[knitbrain setup] --> B[detectPlatforms]
    B --> C{Platform}
    C -->|claude-code| D[claudeArtifacts<br/>.mcp.json + CLAUDE.md]
    C -->|cursor| E[cursorArtifacts]
    C -->|vscode| F[vscodeArtifacts<br/>.vscode/mcp.json + .github/instructions]
    C -->|windsurf| G[windsurfArtifacts<br/>.windsurf/rules + global snippet]
    C -->|codex / zed / copilot-cli| H[Global config writers<br/>--yes writes directly]
    D & E & F & G & H --> I[Universal AGENTS.md]
```

The writer in [src/setup.ts](https://github.com/PDgit12/knitbrain/blob/main/src/setup.ts) emits artifacts non-destructively, never clobbering a user's existing MCP server block, and accepts a `--yes` / `-y` flag so global configs (Codex, Windsurf, Zed, Copilot CLI) can be written directly with a backup rather than printed as a paste snippet. Every setup run also writes a universal `AGENTS.md` so the project follows knitbrain conventions regardless of host.

Per-platform output paths: Claude Code gets `.mcp.json` plus a `CLAUDE.md` instruction file; Cursor and VS Code get merged MCP JSON plus a native instructions/rules file (`.github/instructions/knitbrain.instructions.md` for VS Code, `.cursor/rules/knitbrain.mdc` for Cursor); Windsurf writes `.windsurf/rules/knitbrain.md` plus a global snippet at `~/.codeium/windsurf/mcp_config.json` ([src/platforms.ts](https://github.com/PDgit12/knitbrain/blob/main/src/platforms.ts)). The `GLOBAL_KIND` table maps each global-config platform to its writer kind.

## Hooks (PreToolUse & SessionStart)

Hook handlers live under `src/hooks/` ([src/hooks/index.ts](https://github.com/PDgit12/knitbrain/blob/main/src/hooks/index.ts)) and are dispatched by host into the MCP server. Two hook entrypoints are exposed:

- **PreToolUse** ([src/hooks/pretooluse.ts](https://github.com/PDgit12/knitbrain/blob/main/src/hooks/pretooluse.ts)) — runs before a tool call from the host, allowing knitbrain to inspect or rewrite the proposed call. The most prominent use of this surface is the `knitbrain_read` tool, which in 0.4.4 now accepts absolute paths in addition to paths relative to the server's cwd. This unblocks hosts like Claude Code that pass absolute paths, removing the previous "refused anything outside cwd" fallback that caused user-scoped installs to drop back to the host's raw `Read`.
- **SessionStart** ([src/hooks/sessionstart.ts](https://github.com/PDgit12/knitbrain/blob/main/src/hooks/sessionstart.ts)) — runs at session begin to initialize per-connection state: an agent label for the activity feed, dashboard CRM tagging, and any per-session context the tool dispatcher needs.

The tool dispatcher in [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts) threads a `ToolContext` containing `ccr`, `memory`, `knowledge`, `feedback`, `team`, `meter`, `skills`, `calibration`, and an optional `activity` log with `agentId` — all of which hooks can populate or consult.

## Hub & Operations

The **Hub** is an optional team-wide mirror. The MCP tool `knitbrain_team_post` records findings to the per-project `TeamBoard`; when a hub config is loaded (`loadHubConfig` in [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts)), post events are mirrored via `mirrorToHub` so individual and team views see the same activity stream. Agent lifecycle events (creation, spawn) are explicitly team-visible — the example in [src/mcp/tools.ts](https://github.com/PDgit12/knitbrain/blob/main/src/mcp/tools.ts) shows an `agent created: <name> · scope <scope> · task: <task>` post being mirrored.

Operational surfaces the Hub/operations layer also covers:

- **Profile & evals** — `knitbrain profile` parses host transcripts via [src/learn.ts](https://github.com/PDgit12/knitbrain/blob/main/src/learn.ts) (matches tool_use and tool_result blocks by id) and reports savings; `knitbrain evals` runs the same data through answer-preservation gates.
- **Wire-level compression** — for API-key users, `knitbrain wrap claude` proxies requests through [src/proxy/optimize-request.ts](https://github.com/PDgit12/knitbrain/blob/main/src/proxy/optimize-request.ts), which splits long messages, applies content-type routing, and stabilizes the system prefix via `alignDynamicContent` for cache alignment.
- **Sub-agent operations** — [src/engine/agents.ts](https://github.com/PDgit12/knitbrain/blob/main/src/engine/agents.ts) `proposeAgents` auto-detects candidate domain agents from the knowledge graph, and `writeAgent` persists a scoped subagent to `.claude/agents/<slug>.md` with a sanitized filename, allowed-tools list, review gate, and a `brief` derived from the parent's task + skill body.

The dashboard (`knitbrain dashboard`) auto-detects platform and plan from the MCP handshake plus environment variables, requiring no manual configuration.

## See Also

- [knitbrain MCP Tools & Workflow](mcp-tools-and-workflow.md)
- [Compression Engine & Router](compression-engine.md)
- [Memory, Knowledge Graph & Learnings](memory-and-knowledge.md)

---

*Last verified against knitbrain 0.4.4 — `knitbrain_read` absolute-path fix.*

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: PDgit12/knitbrain

Summary: Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/PDgit12/knitbrain

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/PDgit12/knitbrain

## 3. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: packet_text.keyword_scan | https://github.com/PDgit12/knitbrain

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PDgit12/knitbrain

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/PDgit12/knitbrain

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/PDgit12/knitbrain

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PDgit12/knitbrain

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/PDgit12/knitbrain

<!-- canonical_name: PDgit12/knitbrain; human_manual_source: deepwiki_human_wiki -->