Bug Ledger

Never fix the same bug twice.
A local MCP server that gives AI coding agents a permanent memory of the bugs you already fixed.

What it does

Your agent fixes a bug. You confirm the record. From then on, every session on that project checks the ledger before writing code in that area and can search it while debugging.

• Before coding, the agent calls get_patterns and sees the past bugs for that feature area.
• While debugging, it calls search_bugs with the error text.
• After a fix, you run /logbug. The agent drafts the record, you approve, it is stored.

Everything stays on your machine: one SQLite file in ~/.bugledger/. No account, no cloud, no telemetry.

Install

Requires uv. It downloads Python if needed.

Claude Code

claude mcp add bugledger -- uvx bugledger-mcp

Cursor, in .cursor/mcp.json:

{ "mcpServers": { "bugledger": { "command": "uvx", "args": ["bugledger-mcp"] } } }

Any other MCP client: command uvx, argument bugledger-mcp, transport stdio.

Whole team: commit that JSON as .mcp.json (Claude Code) or .cursor/mcp.json (Cursor) in the repo. Everyone who opens the project gets the server.

Restart the client. /mcp lists bugledger as connected and /mcp__bugledger__logbug is available.

Use

1. Fix a bug as usual.
2. Run /mcp__bugledger__logbug. The agent checks that the session really contained a bug fix, drafts the symptom, root cause, feature area, and stack, shows you the draft, and stores it only after you say yes. Feature work and refactors are refused.
3. Keep working. On connect, the server tells the agent to call get_patterns before coding and search_bugs while debugging. Nothing else to set up.

To make the check a hard rule, add one line to CLAUDE.md or .cursorrules:

Before implementing anything in a feature area, call bugledger get_patterns with that area and this project's name, and account for every returned bug. After fixing a bug, run /mcp__bugledger__logbug.

Tools

Guardrails

get_guardrails returns hand-written Semgrep rules for the classic mistakes agents make: SQL and shell injection, hardcoded secrets, unsafe deserialization, eval, open CORS, debug mode, insecure random, plain HTTP. The agent writes them to .bugledger/ in your repo and adds one workflow file. Existing CI files are never touched. ERROR rules block the pull request, WARNING rules only report. Delete a rule file to drop it.

Data and privacy

• The ledger is ~/.bugledger/ledger.db. Set BUGLEDGER_HOME to move it. Delete it any time; it is recreated on next start.
• record_bug runs git show <commit> locally to store the fix diff. Diffs are never returned by get_patterns and never leave your machine.
• The server makes no network calls.

Contributing

Bug reports, new rules, and pull requests are welcome. Setup, tests, and the release process are in CONTRIBUTING.md.

License

MIT