Skip to main content
Glama

Everyone is wiring coding agents into loops — goal in, iterate until done. Every loop fails the same three ways: the agent lies ("done!" with red tests), it runs away (iteration 47, nothing converging), and it goes broke (context resent and re-derived until the window or the bill gives out).

knitbrain is the substrate those loops run on — a local-first MCP server (37 tools) plus a hook layer for Claude Code, Codex CLI, Cursor, Gemini CLI, and VS Code Copilot:

  • Can't lie — "done" means your verify command exited 0. The loop's gate is a real process exit code, never the model's opinion. Hooks block the agent from stopping while the goal is unmet.

  • Can't run away — every loop carries hard breaks: max iterations, wall-clock deadline, and a per-cycle failure history injected into the next attempt so it converges instead of thrashing.

  • Can't go broke — lossless compression (byte-exact recall, never-expanding), function-level retrieval instead of whole files, persistent memory instead of re-derivation — and a session receipt that shows exactly what was saved and where.

Pure Node, three runtime dependencies, no Python, no ML runtime. Everything lives under ~/.knitbrain; the proxy, hub, and dashboard bind 127.0.0.1. Nothing leaves your machine.

Quick start

npx knitbrain profile      # 1. measure compression on YOUR transcripts — see the number first
npm install -g knitbrain   # 2. install
knitbrain setup            # 3. wire into your agent(s): MCP config, hooks, rules, slash commands
knitbrain onboard          # 4. scan the repo + import past sessions into the brain

Then open your agent and answer the 5-question interview (or just say "onboard this project") — it writes a Project Charter, a per-part workflow, and a loop-ready goal.md. From that point, stating a goal in plain words is enough: the ambient frame turns it into a verify-gated loop. Requires Node ≥ 18.

Related MCP server: kontexta

The three legs

STATE — one brain, every session, every tool

Learnings ranked by outcome (a learning reported wrong is discredited and sinks), an imports/exports/dependents knowledge graph that re-scans itself on read, session handoffs that survive /clear, and a compounding wiki. Onboarding scans your whole toolkit — skills, agents, commands, hooks, across project, global, and plugin tiers — and composes a standing workflow (GOAL, VERIFY, CONSTRAINTS, per-part ROUTING) that re-surfaces every session. The same brain serves every MCP client: explain the project once, Cursor inherits what Claude Code learned.

OPTIMIZATION — lossless, measured, felt

  • Retrieval: knitbrain_search_code returns ranked, score-gated function-level chunks with graph context — the agent reads hits, not trees.

  • Compression: large tool output collapses to a structure-preserving skeleton plus a ⟨recall:hash⟩ handle; the exact original is content-addressed on disk and one call away. Small or incompressible payloads pass through untouched. JSON tool responses are never skeletonized — machine contracts stay parseable.

  • Attribution: every optimization event — MCP tool, hook, or proxy — lands in one ledger, so the session receipt can tell you which door saved what.

ENFORCEMENT — the workflow is not advice

All five major agent platforms now ship hook systems. knitbrain's one hook binary auto-detects the calling platform from the payload itself and speaks its dialect:

Enforcement

Claude Code

Codex CLI

Cursor

Gemini CLI

VS Code Copilot

Deny a violating tool call

✅

✅

✅

✅

✅

Block stop while goal unmet

✅

✅ reason becomes next prompt

➖ follow-up injection

✅ deny + auto-retry

✅

Inject the goal frame

✅ every prompt

✅ every prompt

session start only

✅

✅

Rewrite oversized reads

✅

context pointer

✅ (MCP outputs)

context pointer

✅

Your Project Charter's CONSTRAINTS line is enforced physically: write "NEVER npm publish without OK" during onboarding and the PreToolUse hook denies npm publish at the tool boundary — on every platform above. The differences in the table are each host's documented API ceilings, stated honestly, not gaps we hide.

Loops

One engine, three ways in — the headless loop is the front door:

  • Headless (the front door): knitbrain loop goal.md drives a checkbox goal file outside any editor — survives laptop-close, ticks a box only when the verify command exits 0, and never commits/pushes/deploys. Point any scheduler at it (see Triggers below). Add an independent reviewer with --reviewer "<cmd>" or a REVIEWER: line in the goal file — writer≠judge: both verify AND reviewer must exit 0 before a box ticks, and reviewer rejections feed the next attempt's prompt. knitbrain fan runs N workers in parallel, each in its own git worktree, draining the same queue.

  • Ambient (after onboarding): say what you're working on; the injected frame classifies it — actionable requests become goals driven through knitbrain_run_loop until the verify gate passes; questions get answered directly.

  • Two slash front doors, on every host that has a slash surface (Claude Code, Codex, Gemini, VS Code Copilot, Windsurf — Cursor via terminal):

    • /goal-knitbrain <done-means> drives the gate with you, in this session — knitbrain_run orchestrates a skill + agents, then knitbrain_run_loop runs your verify command each cycle until it exits 0. Single context, interactive.

    • /loop-knitbrain goal.md --for 2h hands off to the external runner (knitbrain loop): it launches detached, spawns a fresh agent per checkbox, and owns the loop itself — surviving your context window, not depending on any model choosing to continue. A slash command can't be an hour-long loop, so it launches the runner and hands back a watch handle.

Self-healing: each failed cycle's verify output is persisted (failures[], last 3) and injected into the next directive — "previous failures — iter 1: …. Address the ROOT CAUSE" — so loops converge in fewer iterations without shortcuts. An adherence gate blocks memory writes until a task was classified: unverified "done" cannot enter the brain.

Triggers

knitbrain is the target of triggers, never the scheduler — your host (cron, launchd, CI, Claude Code /schedule, Codex schedules) owns when; the loop owns honest-until-done. Exit codes are scheduler-friendly: 0 = goal done or clean stop, 1 = gate still red or infra failure — alert on 1.

# weekdays 9am: drive the goal for up to 2h, lint as the independent reviewer
0 9 * * 1-5  cd /path/to/repo && knitbrain loop goal.md --for 2h --reviewer "npm run lint" >> ~/.knitbrain/loop-knitbrain.log 2>&1

Same one-liner works as a launchd ProgramArguments, a CI cron job step, or the command behind your agent's scheduler.

The receipt

Optimization you can't see is optimization you don't trust. When a session ends, the Stop hook prints an honest receipt (also available mid-session via /meter):

— knitbrain session receipt —
consumed ~281k tok · avoided 16.0k tok (5% of what would have been)
top sinks:
  Bash: 10.0k → 2.0k tok (saved 8.0k)
  request: 9.0k → 6.0k tok (saved 3.0k)
  src/big.ts: 6.0k → 1.0k tok (saved 5.0k)
hygiene:
  re-read unchanged ×2: /proj/dup.ts
  1 oversized raw read(s) redirected to knitbrain_read
lifetime: 141.7k tok saved · 394 exact recalls

Honest-math rules, enforced structurally: tokens count as "saved" only when a raw output actually existed and was replaced or redirected — redirects themselves record zero (the follow-up read counts once). Estimates are labeled estimates. A session with no savings says so plainly instead of inventing a number.

Measured, not promised

Run these on your own data — every number below is reproducible with one command.

Measurement

Result

Reproduce

Average reduction over ~3M real tool-result tokens

~46% (≈55% on blocks ≥ 400 chars)

knitbrain profile

Weighted real-shape benchmark (code · logs · JSON · diffs · prose)

68%

npm run bench

Answer preservation (round-trip · identifiers · error/summary lines)

100%

knitbrain evals

These are the ceiling — what you save when output flows through the optimizer. Your realized number is the receipt and the live meter (knitbrain dashboard), which count only what actually passed through. Honest expectations: 60–70% on code/JSON/logs, ~18% on prose, ~48% all-inclusive on measured real sessions — less inside an already-lean harness, more on raw API traffic. And honestly: per-request optimization cannot offset provider cache-cold re-reads or subagent spawns — the meter warns you when a handoff + fresh session is the cheaper move.

How it reaches your traffic

The optimizer is identical everywhere; what differs is reach:

  • API key — a loopback proxy (knitbrain wrap <agent>) compresses every request on the wire, keeps the provider's prompt-cache discount intact (CacheAligner: stable prefix, volatile lines moved to a marked tail), detects the model's context window, and can inject a terse-output directive (KNITBRAIN_TERSE=1).

  • Subscription (OAuth) — the wire can't be intercepted (true for every tool in this space), so knitbrain works through the MCP + hook surface instead: knitbrain_read for files, PreToolUse redirecting oversized raw reads, and PostToolUse skeletonizing Bash/Grep/Glob/WebFetch output in place. Assistant prose lands in the host's transcripts — SessionStart mines new ones into the brain automatically.

Platform support

Platform

MCP tools

Hook enforcement

Auto-compression

Slash commands

Claude Code

✅

✅ full (deny · stop-block · inject · rewrite)

✅ hooks

/goal-knitbrain /loop-knitbrain /meter /handoff /terse (.claude/commands)

Codex CLI

✅

✅ full (.codex/hooks.json)

hooks + knitbrain_read

/goal-knitbrain /loop-knitbrain (~/.codex/prompts)

Cursor

✅

✅ deny + follow-up loop (.cursor/hooks.json)

hooks + knitbrain_read

— (no slash API; documented in rules)

Gemini CLI

✅

✅ deny + AfterAgent loop (.gemini/settings.json)

hooks + knitbrain_read

/goal-knitbrain /loop-knitbrain (.gemini/commands/*.toml)

VS Code Copilot

✅

✅ full (reads .claude/settings.json natively)

hooks + knitbrain_read

/goal-knitbrain /loop-knitbrain (.github/prompts/*.prompt.md)

Windsurf

✅

✅ deny-only (exit-2) (.windsurf/hooks.json)

hooks + knitbrain_read

/goal-knitbrain /loop-knitbrain (.windsurf/workflows)

Cline · any other MCP client

✅

— (advisory; hooks planned where APIs allow)

via knitbrain_read

— (runner works from any terminal)

Any agent, API key

✅

—

✅ proxy (full wire)

—

One hook binary serves every row: it detects the calling platform from the payload and answers in that host's schema. Where a host's API can't do something (Cursor can't block stop; Gemini can't rewrite output), knitbrain degrades to the nearest honest mechanism instead of claiming otherwise. /goal-knitbrain and /loop-knitbrain ship for every host with a slash-command surface — each in that host's native format — so both front doors are the same everywhere. Cursor has no such surface; there the runner is a terminal command (knitbrain loop), documented in its always-on rules.

Commands

Command

What it does

knitbrain (no args)

Start the MCP server on stdio — what your editor invokes.

knitbrain setup

Wire into your agent(s): MCP config, hooks, rules, slash commands, AGENTS.md.

knitbrain onboard

Scan the repo + import past sessions into the brain; start the charter interview.

knitbrain profile

Measure compression on your real transcripts.

knitbrain evals

Answer-preservation gates on your transcripts (exit 1 on failure).

knitbrain loop <goal>

Headless verify-gated loop over a checkbox goal file; --reviewer adds an independent second gate.

knitbrain fan <goal>

Parallel loop — N workers in isolated git worktrees.

knitbrain dashboard

Live local dashboard (127.0.0.1:8790): meter, graph, wiki, activity, plan usage.

knitbrain wrap <agent>

Launch an agent through the optimizer proxy (API-key setups).

knitbrain compress <file>

Terse-rewrite a memory file (e.g. CLAUDE.md); keeps a backup.

knitbrain learn

Mine past sessions for failure → success corrections.

knitbrain terse [level]

Print the terse-output guide (lite / full / ultra).

knitbrain hub / join

Optional team hub — shared findings over one URL and token.

knitbrain statusline

Tokens-saved badge for your editor's status line.

knitbrain prompt

Print the operating prompt (for non-MCP platforms).

Guarantees

Gated by tests and CI, not promised:

  • Lossless — every compressed payload recovers byte-for-byte; the round-trip test gates the build.

  • Never-expand — output tokens ≤ input tokens, always.

  • Answers survive — error lines, result summaries, and top-level declarations are never elided (knitbrain evals, 100% on real transcripts).

  • Machine contracts hold — JSON tool responses are never skeletonized.

  • No false green — the loop marks a task done only after a real verify passes; hooks block premature stops.

  • Honest receipt — savings are counted only when a raw output was actually replaced or redirected; estimates are labeled; zero is reported as zero. Subagent burn (Claude Code Task subagents, Codex CLI's alias) is attributed to the activity ledger via SubagentStart/SubagentStop, so nested-agent token spend isn't invisible to the receipt.

  • Local-first — proxy, hub, and dashboard bind 127.0.0.1; credentials are read locally, sent only to the provider's own endpoint, never logged or stored.

  • Reproducible — every number in this README comes from a command you can run on your own data.

  • Self-audited — knitbrain_self_check runs seven invariants (anti-stale ×2, anti-drift ×2, anti-sycophancy, adherence, context-hygiene) in one pass.

Two integration notes worth knowing up front:

  • Parsing tool results programmatically? A large non-JSON response may carry a trailing ⟨recall:hash⟩ handle — strip it (or retrieve the original) before parsing.

  • The adherence gate blocks close-the-loop writes until a classifier ran this session (KNITBRAIN_STRICTNESS, default block; set warn or off to relax).

Use as a library

import { createOptimizer } from "knitbrain";

const opt = createOptimizer();               // optional: { ccrDir, params }
const r = opt.optimize(bigToolOutput);        // { text, saved, handle, contentType }
const original = opt.retrieve(r.handle);      // exact bytes back

Development

git clone https://github.com/PDgit12/knitbrain && cd knitbrain
npm install
npm run verify        # typecheck · lint · build · test · consistency · bench — all gates
npm run e2e           # end-to-end against the built artifact

Contributions welcome — branch off main, conventional commits, npm run verify green before any PR.

License

MIT

Available Tools

37 tools
knitbrain_classify_taskC

Classify a task into a tier (inquiry/trivial/standard/complex) with phases + plan-mode signal. Follow the returned plan.

Inputs: description (required), files.

knitbrain_compose_skillA

Compose a NEW project-tailored skill for a task in the USER'S OWN composition style (learned from their existing .claude/skills — length, terseness) and persist it. Use when no existing skill fits; refine the body, then knitbrain_skill_save to update.

Inputs: task (required), lessons.

knitbrain_context_meterA

Token-window meter: how full the context is, tokens saved by optimization, and whether it's time to save a handoff and clear the session.

Inputs: no named parameters.

knitbrain_create_agentB

Generate a project-specific subagent (.claude/agents/.md) with 4 guardrails: file scope, allowed-tools, optional review gate, context budget.

Inputs: name (required), scope, tools, reviewGate, +2 more.

knitbrain_get_learningA

Fetch the full lesson for a learning id (from knitbrain_search_learnings).

Inputs: id (required).

knitbrain_learning_outcomeA

Close the loop on a recalled learning: report whether it actually HELPED on this task (a concrete outcome, not 'noted'). Useful learnings rise in future recall; ones reported wrong are discredited and sink, and a correction note folds into the lesson so the next recall carries the fix. This is what turns memory from a log into something that compounds.

Inputs: id (required), helpful (required), note.

knitbrain_load_sessionA

Load the prior handoff + top recent learnings to resume work. Resets the context meter for the new session.

Inputs: no named parameters.

knitbrain_metricsB

Compression telemetry: recall-store tier counts + per-kind retrieval rates (TOIN self-tuning).

Inputs: no named parameters.

knitbrain_onboardA

The front door: onboard a project into the brain. Call with NO args first — it scans the repo + imports this project's past sessions into the wiki, then returns 5 intent questions; ask the user those IN CHAT, then call again with answers (array, in order) to write a Project Charter + constraints that shape the loop and re-surface every session. Run once per project after setup.

Inputs: create, answers.

knitbrain_optimizeA

Compress a payload (JSON / code / prose) into a token-cheap skeleton. The exact original is stored locally and recoverable via knitbrain_retrieve using the returned ⟨recall:hash⟩. Returns the original unchanged if compression wouldn't help.

Inputs: text (required).

knitbrain_pingA

Health check — returns pong and the server version.

Inputs: no named parameters.

knitbrain_propose_agentsB

Auto-detect project-specific agent proposals from the knowledge graph (domains + guardrails). Review/edit, then create with knitbrain_create_agent.

Inputs: no named parameters.

knitbrain_query_dependentsA

Which files import the given file (blast radius before editing).

Inputs: file (required).

knitbrain_query_exportsC

What a file exports.

Inputs: file (required).

knitbrain_query_importsC

What a file imports (module specifiers + names).

Inputs: file (required).

knitbrain_readA

Read a project file OPTIMIZED: returns a structure-preserving skeleton (signatures/schema kept, bulk elided) + a ⟨recall:hash⟩ to page in the exact original. Use INSTEAD of the host's raw read for large files — same information shape, ~70-90% fewer tokens. Works on every platform.

Inputs: path (required).

knitbrain_record_false_positiveA

The classifier got it wrong? Record it: claimed tier vs what the task actually was. After 3 same-direction reports the classifier's threshold self-adjusts (per-project, deterministic, bounded).

Inputs: actual_tier (required), claimed_tier (required), reason.

knitbrain_record_learningA

Record a non-obvious project learning (summary + lesson + tags) for future sessions.

Inputs: lesson (required), summary (required), tags.

knitbrain_retrieveA

Retrieve the exact original bytes for a ⟨recall:hash⟩ handle produced by compression. Use when a skeleton isn't enough and you need the precise content.

Inputs: handle (required).

knitbrain_runA

THE feedback/orchestrator tool — call FIRST when the user states a task. Classifies it (small→big), finds-or-drafts the SKILL for it, proposes guardrailed agents when multi-domain, lists host slash-commands the agent can run itself, and reports the context meter. Follow the returned directive.

Inputs: task (required), files.

knitbrain_run_loopA

Autonomous goal loop (ONE cycle per call). Runs your verify_cmd as the REAL hard gate, tracks iteration across calls, and drives until the goal is met or max_iters. HONEST: the HOST AGENT does the actual work BETWEEN cycles — this tool does NOT edit code. Each call runs the verify gate; if not met it returns a per-cycle directive telling you to make the smallest fix and call again. Stops at grade-pass (met=true) or max_iters (met=false).

Inputs: goal (required), verify_cmd (required), rubric, max_iters, +1 more.

knitbrain_save_handoffC

Save session handoff state so the next session can resume.

Inputs: state (required).

knitbrain_scanA

Scan the project and (re)build the import/export knowledge graph.

Inputs: no named parameters.

knitbrain_search_codeA

Retrieval layer (input SELECTION): query → ranked function/class-level chunks (signature + location, NOT whole files) + graph-connected related files, score-gated so no low-relevance context is served. Use BEFORE reading files: search, then knitbrain_read ONLY the hits you need — sending less beats compressing more.

Inputs: query (required), k.

knitbrain_search_learningsB

Search project learnings; returns ranked headlines (id + summary). Call knitbrain_get_learning for a full lesson.

Inputs: query (required), limit.

knitbrain_self_checkA

Self gap-check (keystone): runs the brain's anti-* invariants in ONE pass and auto-fixes what it can. Re-scans the graph (anti-stale), auto-heals wiki contradictions (Gap-E resolve), confirms a stored workflow surfaces every session (anti-drift), flags learnings recorded with no verify_claim behind them (anti-sycophancy), and reports the adherence write-gate state. Returns a PASS/FAIL invariant table + fixes applied + residual gaps a human must close. Composes the existing detectors — no duplicate logic.

Inputs: no named parameters.

knitbrain_skill_outcomeA

Close the loop on a skill: report whether it actually WORKED after using it (a test passing, a bug fixed — a concrete outcome, not 'task complete'). Failures with a note fold into the playbook's pitfalls; skills that keep failing get flagged needs-revision instead of being re-served.

Inputs: name (required), worked (required), note.

knitbrain_skill_saveC

Persist a refined skill playbook (telegraphic). Same name updates the skill — skills compound across tasks. constraints are non-negotiable guardrails that propagate into every agent briefed with the skill.

Inputs: body (required), name (required), triggers, constraints.

knitbrain_team_boardA

Read the shared team board — compressed skeletons of every posting (cheap to scan; fetch full with knitbrain_team_get).

Inputs: no named parameters.

knitbrain_team_clearB

Clear the shared team board (recall originals are retained until tiered out).

Inputs: no named parameters.

knitbrain_team_getC

Fetch the full original of a board posting by id.

Inputs: id (required).

knitbrain_team_postC

Post a finding to the shared team board (stored compressed; full original recoverable).

Inputs: author (required), content (required).

knitbrain_verify_claimA

Hard claim-check (anti-hallucination): parse a stated codebase fact and check it against the knowledge graph. Supported shapes: " imports ", " exports ", " is a dependent of " / " depends on ". Returns verified | contradicted | unparseable so a claim is settled by the graph, not by assertion.

Inputs: claim (required).

knitbrain_wiki_ingestA

Ingest a synthesized note into the compounding wiki-brain: writes/updates a terse page, rebuilds the index, appends the log, and stubs any cross-referenced page. Use to compound knowledge across the session (entities, concepts, summaries, session notes) instead of letting it vanish into chat.

Inputs: kind (required), title (required), content (required), links.

knitbrain_wiki_lintA

Health-check the wiki-brain: flags claim contradictions across pages (incl. stale claims superseded over time) and orphan pages nothing links to.

Inputs: no named parameters.

knitbrain_wiki_queryA

Query the wiki-brain: returns the index catalog + recent log so you can drill into the relevant pages (read them with knitbrain_read). File good answers back with knitbrain_wiki_ingest so explorations compound.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 37 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, covering different aspects of the project brain system. There is no overlap or confusion between tools.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern starting with 'knitbrain_', e.g., knitbrain_search_code, knitbrain_record_learning. No mixing of styles.

    Tool Count3/5

    37 tools is above the typical recommended range, but the server's scope is broad (project memory, code analysis, collaboration, etc.). It's borderline heavy but each tool serves a specific function.

    Completeness5/5

    The tool set comprehensively covers the project brain domain: learning recording, skill management, code analysis, team collaboration, wiki, session management, and feedback loops. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A local-first MCP server that provides AI agents with safe codebase access through file discovery, hybrid lexical-semantic search, and project introspection. It features durable local memory and semantic indexing while keeping all data and processing entirely on your local machine.
      74
      27 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A local-first MCP server that gives AI coding agents persistent memory and controlled commands. Features a git-backed markdown knowledge vault with FTS5 search, surgical section edits, token-aware context budgeting, and a sandboxed command engine with human approval gates. Works with Claude Code, Cursor, Copilot, Gemini, and more.
      62
      1
      Apache 2.0