Vouch
A git-native, review-gated knowledge base where AI agents propose writes and you approve them.
- Source repo
- vouchdev/vouch
- Stars
- ★ 66
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 71/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Running several Claude Code sessions or agents against one repository that need shared, auditable project memory
- Not a fit if
- Solo users who just need a memory file and no review process
- Teams unwilling to configure an LLM command or API key
- Teams that want fully automatic, unreviewed knowledge writes
- Source review
- 71/100 · Some gaps
What does this agent do, and when should you use it?
Vouch is a repository-resident knowledge base that addresses trust in the write path rather than recall itself. It exposes an MCP server (kb.* tools), a JSONL tool server, and a vouch CLI; agents can only file proposals, and nothing becomes durable until a human approves it via vouch review. Approved artifacts are plain YAML claims and Markdown pages under .vouch/, so knowledge diffs like code, travels with git clone, and is audited through an append-only log of who proposed, who approved, citing what, and when. Every claim must cite a content-hashed source, and an uncited claim is a validation error. vouch compile drives a configured llm_cmd to draft cited topic pages, mechanically verifying [claim: …] and [[wikilink]] markers before drafts reach the same review gate. It ships as a pipx-installable package with a browser console, a Docker image, and Claude Code hooks for session capture and recall.
Vouch reads approved claims, pages, and sources from the .vouch/ directory of your repository. Agents write through MCP tools such as kb.search, kb.read_page, kb.context, and kb.propose_*, or through vouch serve --transport jsonl; proposals land in proposed/ and stay gitignored. During a session, hooks (SessionStart, UserPromptSubmit, SessionEnd, plus opt-in PostToolUse/Stop via capture.realtime) harvest tool calls into a scratch buffer and mechanically roll it up into one pending session-summary page — no LLM involved. vouch review walks pending proposals one at a time, and vouch approve / reject decide them; the approver must differ from the proposer unless you opt out. A claim without a content-hashed source fails validation. vouch compile calls the configured llm_cmd to produce topic pages with [claim: …] citations; drafts whose citations don't hold are dropped before review. vouch recall prints approved claims and page titles into the first turn, size-guarded by recall.max_chars with a truncation notice. Every mutation is written to a committed append-only audit log, and the resulting files are ordinary YAML and Markdown.
- Running several Claude Code sessions or agents against one repository that need shared, auditable project memory
- A team that wants agent-authored project knowledge reviewed with the same discipline as code
- Turning long-lived project context into cross-referenced wiki pages with verifiable sources instead of a pile of notes
- Answering "who decided this was true, on what evidence, and when" from an append-only audit log
- Trying the propose-review-stats loop in the browser via the Docker demo or vouch console before wiring it into a repo
How do you install or deploy this agent?
Try the full UI first with Docker (pre-seeded KB, no setup):
docker run --rm -p 127.0.0.1:5173:5173 -v vouch-demo-data:/data ghcr.io/plind-junior/vouch-demo
# open http://localhost:5173Full UI without Docker — Python only, no clone, no node:
pipx install 'vouch-kb[web]'
vouch serve --transport http --port 8731 &
vouch consoleCLI plus Claude Code integration via the one-liner (POSIX sh, no sudo):
curl -fsSL https://raw.githubusercontent.com/vouchdev/vouch/main/install.sh | shOr directly with pipx (the command stays vouch):
pipx install vouch-kbFor MCP server or CLI-only use via the published image:
docker run -i --rm -v "$PWD:/data" ghcr.io/vouchdev/vouch:latest
docker run --rm -v "$PWD:/data" ghcr.io/vouchdev/vouch:latest statusLocal development from source:
git clone https://github.com/vouchdev/vouch
cd vouch
python3 -m venv .venv && source .venv/bin/activate
pip install -e '.[dev,web]'
vouch --version
make checkHow do you use this agent?
From a project directory, initialize the KB and wire Claude Code in one step:
cd /path/to/your/project
vouch install-mcp claude-codeOr wire it once machine-wide, keeping data per project:
vouch install-mcp claude-code --globalPoint compile at an LLM in .vouch/config.yaml:
compile:
llm_cmd: "claude -p --model sonnet"Work a session normally; on the next session you'll see the pending-review nudge:
🔔 1 auto-captured session summary(ies) awaiting review — run `vouch review`.Approve at the gate, compile the wiki, and approve the drafts:
vouch review
vouch compile
vouch reviewCLI-only review is also supported:
vouch pending
vouch show <id>
vouch approve <id>
vouch reject <id> --reason "..."Commit the knowledge alongside the code:
git add .vouch/ && git commit -m "kb: approve session summary"What are this agent's strengths and limitations?
- A real review gate: agents only propose, the approver must differ from the proposer, and unapproved drafts are excluded from retrieval too
- Every claim requires a content-hashed source; uncited is a validation error, so evidence traces to specific bytes
- Committed append-only audit log plus git history answers who proposed, who approved, citing what, and when
- Approved knowledge is plain YAML and Markdown under .vouch/ that diffs cleanly and travels with git clone
- compile drafts are mechanically verified ([claim: …] and [[wikilink]]) before review, so broken citations never reach you
- A working LLM command (e.g. claude -p) is required for compile, adding model cost on top of the free MIT software
- Many install paths (Docker, pipx, source, global vs per-project install-mcp) force choices during first setup
- Project-scope .mcp.json is never prompt-approved by the VS Code extension, so install-mcp must also write a local-scope entry — easy to misread as connected
- Recall is capped by recall.max_chars, so large knowledge bases surface only a truncated digest at session start
- Pending knowledge is invisible to retrieval, so a fresh KB is only useful after sessions accumulate and get approved
How does this agent compare with similar options?
The README explicitly contrasts vouch with a paragraph in CLAUDE.md, a memory file, or a host's built-in auto-memory: those are enough for a single writer and cost nothing, but cannot answer "who decided this was true, on what evidence" once more than one writer exists. Vouch does not replace that auto-memory; it runs alongside it and puts a review gate in front of the write path.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Vouch This agent | 71 · Some gaps | CLIFree + model costs | ★ 66 | 3mo ago | Python | Claude Code |
| MisakaNet Failure-Memory Library | 74 · Some gaps | MCP serverFree | ★ 556 | today | Python | ChatGPT · Codex · Claude Code |
| Claudexor | 76 · Good | CLIFree + model costs | ★ 523 | today | TypeScript | Codex · Claude Code |
| ZCF - Zero-Config Code Flow | 71 · Some gaps | CLIFree + model costs | ★ 6.1k | 10d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The trust surface is well designed: writes land in proposed/, approve requires approved_by != proposed_by, the audit log is append-only, sources are content-hashed, and SECURITY.md honestly lists non-defended gaps (social-engineered approver, malicious YAML, poisoned supply-chain input). Deductions: the default review.auto_approve_on_receipt: true auto-approves receipt-verified claims, weakening human confirmation; approver_role: trusted-agent lets an agent self-approve; the webapp and MCP server can hold a bearer token and call an external LLM endpoint, so KB content flows to a third party with no redaction or data-flow note; dependencies are only range-pinned with no lockfile or vulnerability-scan evidence. Hence least_privilege=2, user_confirmation=3 (strong default gate but with the receipt exception), data_flow_transparency=2, sensitive_data_handling=1, dependency_security=1, external_effects=2, rollback=2 (supersede/archive/audit history allow recovery but no explicit undo command), source_attribution=3 (content hash + audit events + token subject attribution).
Self-consistency is decent: CLAUDE.md states all three surfaces (MCP/JSONL/CLI) share proposals/lifecycle, test_capabilities enforces method parity, and version sync across four sites is test-tied. But docs drift: docs/getting-started.md and docs/faq.md still say 'not yet on PyPI, lands with 0.1' while README/pyproject are at 1.5.0 and PyPI is live — a direct contradiction. Dependency availability: pyproject gives sensible ranges and extras, but no lockfile, SBOM, or audit evidence. Failure messages: cli.py has _cli_errors translating domain errors to ClickException and server wraps KBNotFoundError, which is adequate. So self_consistency=2, dependency_availability=2, failure_messages=2.
Audience and scenarios are broad: README distinguishes single-writer vs multi-writer and CLI/MCP/JSONL/Web/OpenClaw hosts; AGENTS.md and CLAUDE.md target different agents; docs/INSTALL_FOR_AGENTS.md is a machine-readable install checklist. Capability boundaries are stated (non-defended items, no network service, fixed YAML/MD formats). Trigger precision: skill descriptions are specific (/auto-pr, /pr-precheck triggers), but auto-pr drives claude/codex to open PRs against untrusted third-party repos — a high-impact action; the --autonomy edit default is constrained but still aggressive. Environment fit covers 3.11–3.13, Docker, pipx, source, though the webapp needs node or a prebuilt wheel. So audience_and_scenarios=3, capability_boundaries=2, trigger_precision=2, environment_fit=2.
Information architecture is excellent: README→AGENTS.md→CLAUDE.md→SPEC.md→ROADMAP.md reading order, llms.txt index, topic-split docs/. Install notes are thorough (Docker/pipx/source/one-liner). Examples and FAQ are rich (example-session, faq.md, getting-started). Known limitations are honest (non-defended items, ~10k claim scale, no hosting, no cross-KB sync). LICENSE is MIT and matches pyproject. Deductions: no CHANGELOG in the packet (only AGENTS.md mentions updating it); version drift across docs (faq says not on PyPI); maintenance responsibility is weak — SECURITY.md contact is a placeholder [email protected] and repo URLs mix plind-junior/vouch with vouchdev/vouch, with unverified publisher identity. So naming_stability=2, versioning_changelog=1, maintenance_responsibility=1.
Output usability is moderate: CLI output is structured, supports --json, recall has truncation notices, the review queue is clear; but the webapp defaults LLM_MODEL to an unverified name like gpt-5.4 and chat depends on an external LLM endpoint. Marginal value: README honestly admits a single prompt suffices for solo use, so vouch's gain is real but narrow (multi-writer/audit). Cost-benefit: requires human approval, LLM config, and git commits — high cost for solo projects, reasonable for teams/multi-agent. So output_usability=2, marginal_value=2, cost_benefit=2.
claim_traceability is strong: every claim must cite a content-hashed source, compile's [claim: …] citations are machine-verified, and the audit log records who proposed, who approved, citing what. cross_source_corroboration is moderate: vouch doctor/lint re-hash and flag dangling refs, but no independent third-party reproduction or external benchmark evidence is shown. fact_inference_separation is moderate: the vouch-ask skill requires separating reviewed from UNREVIEWED, and the webapp system prompt forbids filling gaps from general knowledge; but auto_approve_on_receipt lets some claims become 'fact' without human review, weakening the separation. So claim_traceability=3, cross_source_corroboration=2, fact_inference_separation=2.
- Default review.auto_approve_on_receipt: true lets receipt-verified claims bypass human approval; set it to false if you require full human gating.
- approver_role: trusted-agent permits agent self-approval; enable only for fully autonomous setups where the audit log is the sole safeguard.
- The webapp and MCP server can hold a bearer token and call an external LLM endpoint, so KB content leaves the machine; assess data sensitivity and add redaction/network boundaries yourself.
- SECURITY.md contact is a placeholder ([email protected]) and repo URLs mix plind-junior/vouch with vouchdev/vouch; publisher identity is unverified, so the security reporting channel may be unusable.
- Docs drift: faq/getting-started still say 'not yet on PyPI, lands with 0.1', contradicting the 1.5.0 reality and potentially misleading install steps.
- The auto-pr skill drives claude/codex to open PRs against untrusted third-party repos — a high-impact external action; start with --dry-run and review --autonomy settings.
- Dependencies are range-pinned with no lockfile or vulnerability-scan evidence; audit dependencies before production use.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/vouch)<a href="https://followagents.com/en/agents/vouch"><img src="https://followagents.com/badge/vouch.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Added - vouch install-mcp claude-code --global — install once for the whole machine. writes user-level hooks, /vouch-* commands, and a fenced CLAUDE.md snippet under ~/.claude/, and registers vouch as a *user-scope* MCP server (top-level mcpServers in ~/.claude.json), so every claude session in every folder gets capture + per-prompt recall into that folder's own project .vouch/ — the data stays per project; run vouch init once per project. a folder without a KB never captures anywhere: its session opens with a one-line "run …View on GitHub ↗ -
Release notes excerpt
Added - vouch install-mcp <host> now bootstraps the KB when no .vouch/ is discoverable at or above the target, making install a one-command setup. previously it exited 0 with "0 failed" in a fresh project while every installed hook silently no-oped forever (|| true) and the mcp server exited 2 — with nothing ever telling the user to run vouch init. opt out with --no-init (a loud stderr warning then names the remedy); an ancestor KB is reported ("Using existing KB at …"), never shadowed by a second one; unknown hosts still fail …View on GitHub ↗ -
Release notes excerpt
Added - vouch console: serve the vendored React web console straight from the installed package — a same-origin /proxy bridge (loopback-guarded) to vouch serve --transport http backends, reimplementing the vite dev-proxy in python. the built SPA is bundled into the wheel as vouch/web/console (conditionally, via a hatch build hook), so pip install 'vouch-kb[web]' then vouch console needs no node and no repo clone. - kb.activity read method (+ vouch activity CLI mirror): audit-log activity buckets for dashboards — per-day counts with proposal/decision …View on GitHub ↗
FAQ
Why not just put a paragraph in CLAUDE.md?
Does it lock me into Claude?
Does every write require manual review?
Where does the knowledge live, and does anything leave my machine?
What happens when an agent proposes something wrong?
Thanks — we use this to improve the page.