A bug found once
is checked everywhere.

A bug list kept as plain files next to your code. Every bug becomes a lesson, every fix needs a regression test on each surface it hit, and every lesson is checked on your website, apps and server.

 bugs/BUG-0001-cart-total-keeps-the-old-price.md
status: approved
type: money severity: high source: user
surfaces: [shop-web, shop-ios]
patterns: [P-001] # total shown = amount charged
approved: {by: Dana, at: 2026-11-04}
tests: # one per surface, or no fix
What was seenAfter removing a coupon the cart keeps the discounted total; the card is charged the full price.
SURFACESEvery surface it hit, not only where it was seen
LESSONChecked next on every other surface
TESTSA regression test for each one
~/shop $
$ openbugfix fix 1 --commit 4f1c2ab --test shop-web:test/regression/BUG-0001.spec.ts --check "…"
openbugfix: no regression test given for: shop-ios. Every affected surface needs one (--test SURFACE:PATH).
$ openbugfix fix 1 … --test shop-ios:test/regression/bug_0001_test.swift
BUG-0001 → needs review. Tests: shop-web, shop-ios
AGENT
new
Recorded with every surface it hit
AGENT
needs-approval
Cause found, lesson linked
YOU
approved
You decide what gets fixed
AGENT
needs-review
BUG-0001 is here: tested on both surfaces
YOU
done
You check it and accept
FILES
Markdown and YAML in your repo. Every change shows in the diff.
ORDER
fix is refused until it's approved and every surface has a test.
PEOPLE
Agents record and fix. You approve and accept.
LICENCE
Apache 2.0. Python 3.9+, one command.

See every lesson on every surface.
One report. No guessing.

The example shop: a website, an iPhone app and an API, with six bugs at different steps.

openbugfix report · Shop
LESSONWEBSITEIPHONE APPAPI
P-001The total shown is the amount chargedBUG-0001BUG-0001clean
P-002Back restores every choiceBUG-0002cleann/a
P-003Dates in the person's time zoneBUG-0003uncheckedBUG-0003
P-004A pinned panel never covers typingBUG-0004uncheckedn/a
P-005Counts read right, 1 and manytesttestunchecked
P-006Long lists stay fastcleanuncheckedBUG-0005
testguarded by a regression testcleanchecked, no problemBUGhas the buguncheckednobody has looked
~/shop $ openbugfix view
openbugfix · Shop   4 open · done 1 · parked 1

Fixed: needs your review (1)
⚠ 1  money   high  user  web+app
  Cart total keeps the old price
  after a coupon is removed
  how to check: add a 10% coupon,
  remove it, compare total and charge

Waiting for your approval (1)
  3  content med   AI    web+server
  Order date shows tomorrow for
  evening orders in the Americas

Approved: to fix (1)
  2  function med  team  web
  Back button clears the filters

Lessons library L

Thirteen general lessons written for a kind of product, each with how to check it and a test recipe for web, app and server.

WEB · APP · SERVER13 LESSONSADOPT IN ONE COMMAND
Browse lessons

Guide for AI agents AI

Point AGENTS.md or CLAUDE.md at it. Claude Code, Codex, Cursor and others record bugs, prove fixes and sweep lessons. Decisions stay with you.

CLAUDE CODECODEXCURSOR
Read the guide

Built for teams where
agents fix and people decide.

Every step is dated in the bug's own history. The decisions stay with the approver.

How a bug moves
5
STEPS FROM NEW TO DONE
2
OF THEM ARE YOURS
13
GENERAL LESSONS
0
SERVERS OR ACCOUNTS NEEDED
↗

Record

openbugfix new with the surfaces it hit, its type and how severe.

↗

Learn

Link a lesson, or adopt one from the library, so the fix teaches every surface.

↗

Prove

A regression test on every affected surface, or the fix is refused.

↗

Sweep

openbugfix sweep shows which surfaces nobody has checked yet.

Start in a minute.
Plain files, one command.

Needs Python 3.9 or newer, PyYAML and git.

Full README
INSTALL
git clone https://github.com/deepfriedmobile/OpenBugFix.git
python3 -m pip install pyyaml
ln -s "$PWD/OpenBugFix/bin/openbugfix" ~/.local/bin/openbugfix
openbugfix --version
TRY THE EXAMPLE SHOP
cd OpenBugFix/examples/demo-shop
openbugfix view      # the lists, by step
openbugfix report    # bugs and the lesson × surface map
openbugfix web       # the same in your browser
START YOUR OWN LIST
openbugfix init ~/shop --name Shop --owner shop-team --bug-prefix BUG --pattern-prefix P
openbugfix surface shop-web --product Shop --kind web --repo ~/code/shop-web --owner web-team