Gespann

Stop your agents from making the same mistake twice.

Gespann finds the mistakes your coding agents keep repeating, in your git history and agent transcripts. It turns each one into a check that blocks it next time: a hook, a lint rule, a CI check. Prose only as a last resort. Then it measures whether the mistake comes back.

npx gespann scan
See pricing

Free and open source (MIT). Runs on your machine. Needs Node 20 and git.

example-app, last 30 days times seen
  1. gh pr checks 42 --watch Blocks on gh --watch
    14

    hook Since 2 Nov: blocked 3 times, repeated 0 times.

  2. psql …@localhost:5432 Uses the default Postgres port
    9

    hook Proposed. Waiting for your review.

  3. fetch(url) Calls fetch without a timeout
    6

    lint ast-grep rule with a passing and a failing fixture.

  4. docs/api.md Changes the API without updating the docs
    4

    prose One line in AGENTS.md, with a source and an expiry date.

Example output of gespann scan, counted the old way. The top mistake now has a hook.

How it works

Four steps. The first three run on your machine with the free CLI. Nothing in your repo changes until you say so.

  1. Mine

    Gespann reads where your mistakes already left a trail:

    • git: fix commits, reverts, and files that keep getting fixed.
    • Claude Code and Codex transcripts for this repo. A correction like “no, we had this before” counts.
    • The “never do X” lines already in your AGENTS.md and CLAUDE.md.

    Secrets and tokens are redacted before anything is written.

    Terminalexample-app
    $ npx gespann scan --since 30d
Repo: example-app
Since: 2026-10-09  LLM: on
Git: 412 commits, 171 fixes, 6 reverts. Transcripts: 318 Claude, 74 Codex sessions. 96 incidents.

  2. Cluster

    Incidents that are the same mistake get grouped. Each group gets a count, a rough cost, first and last seen, and links to the evidence.

    The ranking is plain: what happens most and costs most comes first.

    An LLM names the clusters if you let it, through your own claude -p or codex exec. With --no-llm no model is called at all.

    Terminalexample-app
    Top recurring mistakes
#  id                   count  cost                  last seen   fix    mistake
-  -------------------  -----  --------------------  ----------  -----  --------------------------------------------
1  cmd-gh-watch         14     ~70 min               2026-11-07  hook   Blocks on gh --watch
2  cmd-pg-default-port  9      4 commits, 61 lines   2026-11-05  hook   Uses the default Postgres port 5432
3  fetch-no-timeout     6      6 commits, 112 lines  2026-11-03  lint   Calls fetch without a timeout
4  api-docs-drift       4      4 commits, 38 lines   2026-10-30  prose  Changes the API without updating docs/api.md

Wrote .gespann/report.json and .gespann/report.md
Next: gespann propose cmd-gh-watch

  3. Escalate

    Each mistake gets the strongest guardrail that fits:

    1. hookRejects the command before the agent runs it, and says what to do instead.
    2. lintAn ast-grep rule for code the agent writes.
    3. CIgespann check runs every guardrail on each pull request.
    4. proseOne short line with a source and an expiry date. Last resort.

    Every guardrail ships with a passing and a failing fixture and has to pass both. You review it, then apply it. Nothing is applied silently.

    Terminalexample-app
    $ npx gespann propose cmd-gh-watch
Proposed hook guardrail "cmd-gh-watch": Blocks on gh --watch
Files in .gespann/guardrails/cmd-gh-watch: hook.mjs, settings.snippet.json, fixtures/fail.json, fixtures/pass.json
Validation:
  ok   patterns compile: 2 pattern(s)
  ok   failing fixture is blocked: exit 2
  ok   passing fixture is allowed: exit 0
  ok   bad input is ignored: exit 0
Review it, then run: gespann apply cmd-gh-watch

$ npx gespann apply cmd-gh-watch
Applied "cmd-gh-watch". Changed:
  .claude/hooks/gespann-cmd-gh-watch.mjs
  .claude/settings.json

    Next time the agent tries it:

    Agent runs
    gh pr checks 42 --watch
    Hook answers
    Blocked by gespann guardrail cmd-gh-watch: Do not block on `gh pr checks --watch` or `gh run watch`. Check once with `gh pr checks`, or use the native PR watcher.
    Agent runs
    gh pr checks 42

  4. Measure

    A guardrail is only worth keeping if the mistake stops. gespann check proves every guardrail still works, locally or in CI.

    Gespann Cloud keeps the history: how often each mistake comes back, and how often each guardrail stopped an agent. Locally, gespann review tells you which applied guardrails held.

    cmd-gh-watch
    3, 4, 3, 4 a week. Then the hook. Then 0.

    CIexample-app
    $ npx gespann check
ok   cmd-gh-watch (hook)
  ok   patterns compile: 2 pattern(s)
  ok   failing fixture is blocked: exit 2
  ok   passing fixture is allowed: exit 0
  ok   bad input is ignored: exit 0
ok   fetch-no-timeout (lint)
  ok   failing fixture matches: 1 match(es), line 3
  ok   passing fixture is clean: no match
All 2 guardrails pass.

Why not just add another line to CLAUDE.md?

You already did. Probably three times.

Instruction files grow, contradict each other and get cut off. Claude Code loads only the first 200 lines of its MEMORY.md. A rule on line 201 does not exist. And a rule the agent can read is still a rule it can skip.

A hook cannot be skipped. It reads the command before it runs and says no, with the right alternative. A lint rule fails the build no matter which agent wrote the code.

So Gespann writes prose only when nothing stronger fits, and then as one short line with a source and an expiry date.

MEMORY.md, lines 196 to 204
  1. 196- Never run gh pr checks --watch. Check once.
  2. 197- Use port 55432, not 5432.
  3. 198- Do not run bench.sh down --all.
  4. 199- Seriously. Not 5432.
  5. 200- Never push with --force. Use --force-with-lease.

Line 200. Claude Code stops reading here.

  1. 201- NEVER run gh pr checks --watch!!
  2. 202- fetch() always needs a timeout.
  3. 203- Update docs/api.md with every API change.
  4. 204- 5432. Again. Why.

One harness for every agent

Gespann is German for a team of animals in one harness. One set of rules for every agent you run.

Your agents do not share memory. Each vendor’s memory works for its own agent on one machine. Guardrails live in your repo, so every agent, every machine and every teammate gets the same ones.

  • Claude CodeReads its transcripts. Hooks install into .claude/settings.json.
  • CodexReads its sessions. Hooks go into .codex/hooks.json, prose rules into AGENTS.md.
  • CursorLint rules and CI checks catch what it writes. Transcript mining is coming.

Built from one repo’s scar tissue

In the founder’s main repo, 48 % of commits are fixes. 26 % of 3,524 agent threads are reviews of what an agent just did.

And one file has been fixed 101 times.

101 fixes to one file. Gespann exists so the 102nd is a blocked command instead.

Your code stays on your machine

The CLI runs locally and sends nothing. Only gespann sync, the Cloud part, talks to our server, and it sends counts, not content.

What gespann sync sends

  • Mistake ids, hashed on your machine with a key that belongs to your account. Built-in rule ids like cmd-gh-watch stay readable.
  • Per mistake: its kind, counts, and the days it was first and last seen.
  • Repo totals: commits, fix commits, reverts, agent sessions, incidents.
  • Guardrail ids and whether each check passed.
  • How often each guardrail blocked an agent, per day.
  • The CLI version.
  • A hash of the repo. With --names also its name and readable mistake ids, which can contain file or command names.

What it never sends

  • Code.
  • Transcripts or prompts.
  • File paths.
  • Commit messages.

Do not take our word for it. gespann sync --dry-run prints exactly what would be sent, and sends no scan data.

Terminalshortened
$ npx gespann sync --dry-run
{
  "version": 1,
  "cli_version": "0.1.0",
  "repo": { "hash": "9f2c41d8…e41a" },
  "window_days": 30,
  "stats": { "commits": 412, "fix_commits": 171, "incidents": 96, … },
  "mistakes": [
    { "id": "cmd-gh-watch", "suggestion": "hook", "count": 14, … },
    { "id": "h:5b1e07c2a9f4", "suggestion": "lint", "count": 6, … }
  ],
  "guardrails": [
    { "id": "cmd-gh-watch", "kind": "hook", "ok": true, "warn": false }
  ],
  "blocks": [
    { "guardrail": "cmd-gh-watch", "day": "2026-11-06", "count": 2 },
    { "guardrail": "cmd-gh-watch", "day": "2026-11-07", "count": 1 }
  ]
}
Dry run. Nothing was sent.

Pricing

The CLI is free forever. Pay for Cloud when you want history, more repos or a team view. Pay yearly and get 2 months free.

Free

For trying it on one repo.

$0forever

No card needed.

Create free account Install the CLI
  • The CLI: scan, propose, apply, check.
  • Everything runs locally. MIT licensed.
  • Cloud for 1 repo.
  • 14 days of history.
  • Dashboard.

Pro

For one developer.

Billing for Pro

$29per month

$290per year

Or $290 a year.

That is $24.17 a month.

  • Everything in Free.
  • Unlimited repos (fair use: up to 200, more on request).
  • 12 months of history.
  • Weekly email report.
  • Blocks counted per guardrail: how often each one stopped an agent.

Coming, included in Pro when it ships:

  • GitHub App that mines every PR and opens guardrail PRs.
  • Guardrail registry, ranked for your stack.
  • Pro rule packs.

Team

For teams of 2 or more. Priced per seat.

Billing for Team

$49per seat per month

$490per seat per year

Minimum 2 seats.

  • Everything in Pro, for every seat.
  • One shared dashboard for all members.
  • Required guardrails: each sync lists the repos that are missing one.
  • Member management.
  • Unlimited history.

Prices in USD, excluding VAT and sales tax. Monthly or yearly, self-serve. Cancel anytime in the billing portal.

Payments are handled by Dodo Payments, our merchant of record. They charge the tax and send the invoice. Not happy? You get a full refund within 14 days of your first payment. See the refund policy.

Questions

Do I need Gespann Cloud?

No. The CLI finds mistakes, writes guardrails, tests them and installs them on its own. Cloud adds history across time, repos and people, and counts how often each guardrail blocked an agent.

Does Gespann send my code anywhere?

No. The CLI reads your repo and transcripts on your machine. gespann sync sends only ids, counts and pass or fail results. Run gespann sync --dry-run to see every byte first.

If you let the CLI use an LLM, it calls your own claude -p or codex exec, under your own account. We never see that either.

Will it change my repo behind my back?

No. propose writes into .gespann/ and tests the guardrail against its fixtures. Your repo changes only when you run apply, and you can read the diff like any other.

Which agents does it work with?

Claude Code, Codex and Cursor. It reads Claude Code and Codex transcripts today. Hooks install into Claude Code and Codex. Lint rules and CI checks do not care which agent wrote the code.

Is the GitHub App ready?

No. It is coming. When it ships it is included in Pro and Team at no extra cost. Until then, run gespann scan locally or in CI.

What happens if I cancel?

Your plan runs until the end of the period you paid for. Then your account becomes a free account. We keep your full history for 30 days, in case you come back. After that, history older than 14 days is deleted, as on the free plan. Once no paid plan runs and no team members remain, you can delete your account and all its data on your account page.

The CLI keeps working. It never needed us.

Can I get a refund?

Yes, within 14 days of your first payment. Write to [email protected] from your account email. Details in the refund policy.

How does Team billing work?

You choose the number of seats at checkout, at least 2. Each member uses one seat. Monthly or yearly, like Pro.

Who is behind Gespann?

TecMinds GmbH, a small software company in Lucerne, Switzerland. See the imprint.

Find out what your agents keep getting wrong.

One command. Free, local, no account needed.

npx gespann scan