latch MCP server

---

The payoff isn't only fewer mistakes — it's speed. Because the agent stays inside decisions you've already made instead of re-opening a settled call, you re-catch less and can hand it more: run several agents in parallel without babysitting each one to check it isn't rebuilding a path you ruled out three sessions ago. That's the part cheaper-context and history-search tools don't give you — not better recall, but earned confidence that the agent is working inside your judgment.

You can still override any verdict; reviving a rejected path just becomes a visible, cited decision instead of silent drift. The judgment stays yours; latch just keeps the agent inside it.

New here? Try the gate in ~2 minutes without touching your data — or seed it from your own sessions and watch it catch a decision you actually made.

The receipt

A fresh agent proposes a path this project already rejected:

Request: Add multi-user accounts by moving the datastore from local SQLite to a hosted Postgres service.

latch's gate fires before any edit — and returns the receipt:

Recommendation: DO_NOT_PROCEED
Summary: The request directly repeats the rejected path in the KB: moving the local SQLite datastore to a hosted/client-server database such as managed Postgres to add multi-user accounts or sync (id=1). The canonical decision is to keep the demo app local-first on a single embedded SQLite file, with export/import as the allowed data-movement path.
Risk if proceed: It would violate the explicit local-first SQLite constraint and reopen a path already rejected for this demo app.
Better next action: Keep SQLite and implement any cross-machine data movement as an explicit export/import flow with documented limits.
Cited evidence:
- id=1 decision status=canonical: Keep the demo app local-first on SQLite — no hosted database
Worktree changed before/after gate: no

Read it field by field:

Field	What it is
Recommendation	The go/no-go verdict: DO_NOT_PROCEED.
Summary	The settled decision and exactly why the request conflicts with it.
Risk if proceed	What breaks if the agent ignores the decision.
Better next action	The compliant alternative to take instead.
Cited evidence	The exact source node: id=1, kind decision, status=canonical.
Worktree changed	no. The gate ran before edits. Nothing on disk moved.

That last line is the point. The rejected path was caught and cited, and your tree is untouched.

This exact receipt is checked in at proof/README.md, captured with the codex backend. It comes from a synthetic no-history demo, so it proves the gate path — not that latch read anyone's real history. Seeding your own sessions is what does that.

Why a gate, not a rule

Give an agent your history and it becomes better-informed, not bound: a bigger transcript is still just context it can talk past. Give it a spec, a rule, or a CLAUDE.md and you hand it authority it can ignore — or quote in one breath and violate in the same diff.

latch is the runtime gate that closes that gap. It keeps your project's cited decisions, rejected paths, preferences, rationale, and evidence in a local KB, then puts a go/no-go verdict in the agent's path before files change — and shows you the receipt. That is decision continuity, not a bigger transcript or a generic recall layer.

It runs locally on one SQLite KB, needs no cloud account, and targets macOS, Windows, and Linux. Claude Code, Codex, and Cursor share the same KB, so judgment captured through one agent can gate another.

How the check reaches the agent is host-dependent, and latch is honest about it: on hosts with lifecycle hooks (Claude Code, and Cursor with hooks enabled) the gate runs before edits as part of the loop; on hosts without them the managed contract asks the agent to run it, and every receipt records whether the gate actually ran.

Where latch sits next to tools you already use. Different layer, not a bigger prompt:

Tool	What it's for	How its authority works
Instruction / memory files (CLAUDE.md, AGENTS.md, Cursor rules)	Standing guidance for the agent	Prompt-enforced — the agent can ignore it, rewrite it, or quote it while violating it
Transcript / session search	Recover what was said or done before	Passive — surfaces the past only when a human thinks to look; checks nothing before an edit
Issue / task trackers	Coordinate what to work on	Organizational — track the work; they don't gate how it gets implemented
Spec / constitution frameworks (e.g. spec-kit)	Declare project rules and gates up front	Prompt-enforced — a "must pass" gate is markdown the agent reads, with no runtime check
latch	Check the next action against decisions you've already ratified	Runtime-checked — a go/no-go verdict with a cited receipt, before files change

Why not just a spec-kit extension? An extension of a prompt-based framework inherits the same failure class — the rule still reaches the agent as text it can talk past. latch runs the check as code at the action boundary, so it complements those tools rather than competing with them.

And the check is cheap: the per-prompt retrieval hook runs locally in roughly 120–150 ms, and the gate itself is a model call that fires only on write-shaped work — never on every prompt. Numbers and repro scripts are in Safety and control.

How it works

Five moving parts, one local engine — the same vocabulary you'll find in ARCHITECTURE.md:

1. A typed knowledge graph in one SQLite file. Decisions, rejected paths, preferences, facts, and open questions are typed nodes linked by edges — local, inspectable, no cloud account.
2. Staging before authority. Newly captured knowledge lands in staging; seeding is review-first, so nothing your agents recover becomes project judgment without you.
3. Explicit ratification, kept append-only. Promotion, supersession, and reconciliation are recorded as history rather than rewrites — a ruling gets superseded by a newer decision, never silently edited, and the receipt names each cited node's current status.
4. Hybrid retrieval, bounded. FTS5 keyword search plus vector similarity over local MiniLM embeddings (via sqlite-vec), fused with reciprocal-rank fusion and expanded through bounded graph neighborhoods — all on-device.
5. A gate that shows its work. On write-shaped requests the gate assembles the relevant rulings and returns a go/no-go verdict citing the exact nodes (id, kind, status) it relied on — the receipt you saw above.

What you get on day one

Install and seed once, and from the next session on:

• Every decision on file is one you ratified. Seeding is review-first — --apply writes only the candidates you approve, so nothing is kept that you didn't sign off on.
• The gate runs on coding-shaped work and returns a go/no-go verdict citing the exact decision it relied on, before any file changes. On Claude Code and hook-enabled Cursor it runs as part of the loop; on hosts without lifecycle hooks the contract asks the agent to run it, and every receipt records whether it actually did.
• You get a receipt, not an assurance. latch shows a short foreground receipt when it shapes an answer or a gate fires, and /latch-gate-report audits recent gate activity without writing.
• Shared across your agents. A decision captured through Claude Code gates Codex and Cursor too — install per repo to give each one its contract, but the judgment is shared.
• Your session start stays quiet. A healthy session start injects no standing project brief — at most five compact pointers, when they're relevant.
• Today's judgment carries into tomorrow, when you ask for it. /latch-compact at a stopping point is user-initiated by design — it spends a model call — and writes the session's decisions down, so the next session inherits them instead of re-deriving them.

What day one does not give you is a catch you didn't seed: the gate is only as good as the decisions you've ratified, and the honest limits are in Where the gate doesn't help.

Get started

Prerequisites: Git, and a runnable CLI for every agent surface you choose to wire — Claude Code, Codex, or Cursor Agent.

Using Codex Desktop on Windows? The desktop app does not by itself prove that Latch can launch the Codex CLI for model-backed gates, seeding, compaction, and maintenance. In PowerShell, codex --version must succeed. If it does not, install the standalone CLI, close and reopen PowerShell, and rerun the Latch installer:

irm https://chatgpt.com/codex/install.ps1 | iex

Latch's local MCP search/get/insert server is Python-based; this CLI check is for the model-backed operations that Latch runs as subprocesses.

Install in one command. Open a terminal in the repo you want latch to protect.

macOS, Linux, or Windows Git Bash:

curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/open-latch/latch/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/open-latch/latch/main/install.ps1 | iex

That's the install. The quickstart wires your agent and then prompts you to seed. Fully quit and reopen the agent, then create a new task so its tools and hooks load. An already-open task is not a valid MCP check; in a new Codex task, ask it to call latch_recent(limit=1) for live host-level proof.

Then seed — this is the real first step, not an optional demo. From here latch captures decisions as you work; seeding is how you skip the wait. It backfills what your project already settled, so the gate has something of yours to cite today rather than in three weeks. Point it at your recent sessions:

/path/to/latch/bin/latch_seed.sh --source both --last-sessions 20 --apply
# Windows: C:\path\to\latch\bin\latch_seed.ps1 --source both --last-sessions 20 --apply

# Opt in to this project's local Cursor IDE history:
/path/to/latch/bin/latch_seed.sh --source cursor --cursor-history --last-sessions 20 --apply

It is review-first — the pass prints a structured report and writes only the candidates you approve (enter none at the prompt to dismiss the whole report without writing anything). It recovers what your transcripts actually contain, not everything you have ever decided; whatever it misses gets captured as you work. --cursor-history is opt-in and never implicit: it reads only IDE conversations assigned to this project, excludes CLI sessions, cloud chats, and subagents, and fails closed if Cursor's metadata is missing. The full walkthrough, source options, and review flags are in See it catch and the first-run mission; to read the installer first, pin a release, or install to a custom directory, see Install details.

Try it in 2 minutes

No history you want to point latch at yet — or want proof before seeding? Run the public-safe fixture in a throwaway repo. It exercises the full gate path without reading any of your data:

/path/to/latch/bin/latch_demo_no_history.sh
# Windows: C:\path\to\latch\bin\latch_demo_no_history.ps1

The fixture is synthetic — it proves the gate fires, not that latch understood your history. Seeding your own sessions is what makes the catches yours.

See it catch: seed, then gate

The fixture proves the mechanism. The value is catching a decision from your history that your next agent would plausibly revive.

1. Seed your history (you did this in Get started — here are the source options). Use --source claude, codex, cursor, both, or all; --apply is review-first and writes only the candidates you approve, while omitting it previews only. From a hooked Cursor conversation, /latch-seed is the normal path; Cursor uses only that exact hook-provided transcript and never scans history. For an explicit project-history backfill, run the shell seed command with --cursor-history; the normal bounded source and staging review still apply.

2. Pick one strong proof target the seed surfaced:

• a concrete rejected approach or governing rule,
• the reason or allowed alternative,
• source and current status evidence,
• enough specificity that another agent could plausibly violate it.

3. Ask an agent to implement that rejected approach. Expect a foreground Latch gate receipt before edits, cited against your own decision. A SKIPPED, recommendation: null, empty-evidence, or PROCEED result on a plainly violating request is not the proof.

Prove no edits with your own eyes. Capture git status before and after a real gate call:

git status --short > /tmp/latch-proof.before
/path/to/latch/bin/run_latch_gate.sh '<generated request>' | tee /tmp/latch-gate-proof.json
git status --short > /tmp/latch-proof.after
diff -u /tmp/latch-proof.before /tmp/latch-proof.after

The diff should be empty — the gate ran, and no files moved.

No history to seed yet? Run the 2-minute fixture from Get started — it proves the gate path without touching your data. The first-run mission and the proof-ready demo runbook carry the exact paths, success criteria, and receipt checks.

Supported agents

The guided quickstart wires whichever you choose.

Agent	What latch installs	Boundary
Claude Code	MCP tools, hooks, slash commands, /latch-compact, managed CLAUDE.md contract	Restart after install so tools and hooks load
Codex	Shared MCP tools + KB, user skills, AGENTS.md, silent startup hook, Codex backend defaults	Start a new task after install; compaction is manual
Cursor	Project MCP, Rule, commands, skills, AGENTS.md; optional session/gate/activity hooks	Current-session seed/compact; opt-in project-local IDE history backfill
Multiple agents	One shared local latch KB	A decision captured through one agent can gate the others

Cursor also needs three user-controlled live steps: authenticate with agent login, approve the project MCP server, and enable latch in Cursor Settings > Tools & MCP. Static doctor success alone does not prove the IDE gate is live. Per-surface manual install and doctor commands live in ARCHITECTURE.md; see the Cursor reference and Cursor gate smoke.

Using latch day to day

You mostly do not operate latch. Once wired, the agent reads the KB before answering, captures durable decisions as they happen, and runs latch_gate before coding-shaped changes — showing a short foreground receipt when latch shapes an answer or a gate fires. Audit recent gate activity without writing anything via /latch-gate-report or bin/latch_gate_report.sh.

At natural stopping points, capture the session so tomorrow's agent inherits today's judgment. Compaction is user-initiated because it spends a model call and writes a durable summary into the KB:

• Claude Code: /latch-compact
• Codex: run the installed latch-compact skill (Codex has no top-level /latch-* command)
• Cursor: /latch-compact from the current hooked conversation

Or, you can simply ask latch in natural language, and the agent will offer the matching command.

Using latch in more than one repo

You install latch once. The runtime and your KB are shared, and for Claude Code and Codex the tools and hooks are registered per-user — so the engine is already reachable in every repo on your machine. What each repo still needs is its own contract: the managed CLAUDE.md / AGENTS.md block that tells the agent to actually consult latch and run the gate before it acts. (Cursor is wired entirely per-repo — its MCP server, rule, and commands all live in the project.)

So to protect another repo, run the install command — or /path/to/latch/bin/latch_quickstart.sh — from inside that repo. It reuses the same pinned KB and just writes that repo's contract; then restart the agent. Without this step a new repo may show latch's tools but never be told to use them.