Your AI agent has a blind spot. found-issues is the Claude Code and Codex plugin that makes it log, track, and auto-close the bugs it would otherwise shrug at.
7 lifecycle hooks · 14 slash commands · 2008 tests on Linux/macOS · zero manual bookkeeping
Without found-issues:
"Note:
parseConfigswallows JSON errors silently — pre-existing, not related to our change. Continuing with the refactor."
The observation is gone the moment the session ends.
With found-issues:
"Out of scope for this task — logging it."
- [open] 2026-07-10 src/config.ts:88 — parseConfig swallows JSON errors (suggested: rethrow with path context)
The statusline ticks to 1 issue, the entry survives every future
session, and it flips to [fixed] on its own the day a PR fixing that
line merges.
Run these in Claude Code, then start a new session:
/plugin marketplace add AltDoug/claude-plugins
/plugin install found-issues
Zero config — logging starts working immediately. One recommended step:
/found-issues:setup
That wires the statusline counter (so open issues stay visible at a
glance), the optional /fi shortcut, and the optional git pre-commit
hook. SSH install errors and update/uninstall details: footnotes below.
found-issues is dual-harness — the same plugin installs into OpenAI Codex:
codex plugin marketplace add AltDoug/claude-plugins
codex plugin add found-issues
found-issues install-codex-hooks
install-codex-hooks is a required one-time step (its entries survive
codex plugin update since 2.10.3; re-run it when a release adds a
hook): Codex 0.144.5 removed plugin-bundled hooks, so
found-issues wires SessionStart / format-enforcer / branch-guard /
annotator / first-touch into Codex's own $CODEX_HOME/hooks.json instead. Then start a
new Codex session. The ledger (docs/found-issues.md) is shared across
harnesses with no migration or sync step — a repo worked on from both
Claude Code and Codex is just one ledger. Skills are available as
$fi-log, $fi-sync, $fi-status, etc. Run /hooks once in Codex to
trust the new hook entries; found-issues doctor checks the wiring. Details
and the one gap (no statusline on Codex): AGENTS.md.
Just work normally — Claude logs out-of-scope findings on its own. To poke the system:
"What's open in found-issues?" · "Show me the critical ones" · "Run /found-issues:fix"
At the start of each new session the hook loads the agent rules plus a short
ledger summary (the critical entries and a status line); a file's own open
entries appear when you first read or edit it. Plain-English queries work
without any command, and found-issues list shows everything.
The agent maintains a docs/found-issues.md file in each repo:
- [open] 2026-05-08 lib/foo.py:42 — null check missing (suggested: add guard)
- [open] [!] 2026-05-08 src/auth.ts:88 — leaks token in error (suggested: redact)
- [open] 2026-05-08 src/queue.py:12 — race on flush (PR: org/repo#42)
- [fixed] 2026-05-06 src/auth.ts:88 — race on session refresh (PR: org/repo#41) (fixed: 2026-05-08)
The closure loop runs on its own:
| When | What happens |
|---|---|
| Claude notices an out-of-scope issue | Logs it via /found-issues:log per the rules injected at session start |
| Claude opens a PR addressing an entry | Hook writes a non-closing suggestion on line-matched entries and prints the /found-issues:annotate-pr <N> --pick command that confirms the ones the PR fixes |
| Claude commits a fix directly to main | Same, with /found-issues:annotate-commit <sha> --pick |
| PR merges or commit lands on main | Background sync flips [open] → [fixed] automatically — instantly when merged from inside the session, within ~10min for external merges, always at the next SessionStart as a fallback |
| Referenced file/line is deleted | Tombstone detection auto-closes the entry |
| Branch with un-promoted entries about to be deleted | pre-branch-delete hook blocks until /found-issues:promote runs |
You see a count at session start, and in your statusline:
The file stays accurate. [fixed] history accumulates as a record.
A CLAUDE.md rule gets you the logging — for a while. It doesn't get you:
- Enforcement. Hooks reject malformed entries, block branch deletion while entries would be orphaned, and re-prompt the check every working turn — the discipline survives long sessions and model drift, because it's mechanical, not remembered.
- A closure loop. Entries flip to
[fixed]automatically when the fixing PR merges, or when the cited code is deleted. Prompt-only logging accumulates a stale file nobody trusts. - Visibility. The statusline counter (
3 critical · 12 other) keeps known debt in your face instead of in a file nobody opens. - The ledger fixes itself.
/found-issues:fixre-verifies every open entry against the current code, triages what's genuinely auto-fixable, fixes on a branch with tests, and ships a precisely annotated PR — with the guardrails (never re-fix ghosts, never guess at externally-gated fixes, never over-annotate) a bare prompt can't encode.
How it differs from Linear / Jira / Backlog.md: docs/faq.md.
All namespaced under /found-issues: (Claude Code plugin convention):
| Command | Use |
|---|---|
/found-issues:log <path:line> — <symptom> |
Log a new entry (Claude does this proactively) |
/found-issues:sync |
Reconcile with PR/commit history + AI-verify unannotated entries |
/found-issues:fix [--auto] [--only <path>] |
Verify, triage, and fix the open entries — gated batch-fix that ships an annotated PR (--auto skips the gate, auto-fixable bucket only) |
/found-issues:annotate-pr <N> |
Link an entry to a PR (auto-prompted by hooks) |
/found-issues:annotate-commit [<sha>] |
Link an entry to a commit (defaults to HEAD) |
/found-issues:defer <path:line> [--reason <text>] |
Mark an entry as deferred (suppress from counter) |
/found-issues:promote-deferred <path:line> |
Promote a [deferred] entry back to [open] |
/found-issues:promote |
Carry branch-only entries into main before branch deletion |
/found-issues:status |
Print current counts |
/found-issues:decide |
List the questions blocking (decide: …) entries, or record an answer (v3) |
/found-issues:archive |
Move old [fixed] entries to docs/found-issues-archive.md (50-entry / 30-day thresholds) |
/found-issues:setup |
Optional first-run orientation |
/found-issues:doctor |
General health check — CLI, statusline, gh, mode, hook opt-outs, issues file |
/found-issues:uninstall |
Clean up plugin-private state before /plugin uninstall |
/found-issues:setup offers an optional /fi shortcut so /fi log src/foo.py:42 — bug works as a shortcut for the full namespaced form.
Off by default. With found-issues config autofix true in a GitHub repo
(gh signed in, a test command), entries tagged (fix: small) are fixed
in the background, each in its own worktree, branch and PR; when 5 are
fixable (setup lets you pick 5, 10, 20 or any number), one sweep fixes up
to 8 in a single PR. Each fix must pass the repo's tests and a read-only
reviewer model. A run whose tests already fail before any change ends at
once, before it spends anything, and a sweep whose PR could not be pushed
keeps its branch and retries. The fix starts from, and its
PR opens into, the branch your session is working on (its landing branch),
not always the default branch; a file with uncommitted or unpushed changes
in your checkout waits until you push it.
- Fix PRs merge themselves — no human approves them.
- Runs bill your Claude or Codex account, including in the background.
Default caps per repo: 5 spot fixes and 1 sweep a day. There is no dollar
cap unless you set one (
found-issues config autofix.runBudget <usd>,autofix.sweepBudget <usd>). Codex runs use pinned models (gpt-6.1-solfor fixing,gpt-6-astrafor verifying;inheritkeeps your own) and can stop at a token cap (autofix.codexRunTokens,autofix.codexSweepTokens). - See it:
🔧N(running) and❓N(decisions waiting) in the statusline,found-issues autofix status, a "since last session" line at session start, andfound-issues doctor. - Readiness: auto-fix only queues where a test command exists, and sizes
its run limit from the measured suite. A repo that cannot run it gets one
"Auto-fix is waiting in this repo" line at session start;
found-issues autofix readyshows why. - Stop it:
found-issues autofix off(every repo),found-issues autofix cancel <id>(one run),FOUND_ISSUES_AUTOFIX=off(one shell).
/found-issues:setup walks through it. Design:
docs/superpowers/specs/2026-10-03-autofix-v3-design.md.
When the statusline reads 3 critical · 12 other, it's a constant
reminder there's known work waiting. The critical flag ([!]) bubbles
drop-everything items to the top.
[deferred] is a first-class state — tracked in the file, suppressed
from the statusline counter, and flagged when it recurs. Touch a
deferred entry enough times and the plugin nudges you to promote it
back to [open]. Critical entries auto-promote. Re-defer escalates the
nudge threshold geometrically (loop prevention). Full lifecycle:
docs/deferring.md.
Entries are markdown checklist lines:
- [STATUS] [!] YYYY-MM-DD path:line — symptom (annotations…)
Statuses are open / deferred / fixed. [!] is the optional critical flag. Annotations like (PR: org/repo#N) and (commit: <sha>) are optional but enable auto-flipping. Full grammar, regex, and edge cases: docs/format-spec.md.
Auto-detects 4 modes per repo: local, git, github-direct, github-pr. Mixed workflow (sometimes PR, sometimes direct push) is fully supported — mode just sets the default closure mechanism. Detection logic, mode table, and edge cases: docs/modes.md.
| OS | Shell | Status |
|---|---|---|
| Linux (Ubuntu) | bash | ✅ Supported |
| macOS | bash | ✅ Supported |
| Windows 11 | Git Bash |
The CLI and hooks are bash-based, so on Windows you need a bash interpreter — that's what Git for Windows (Git Bash) provides. WSL works too. CI runs the full test suite on Linux and macOS; the Windows leg was retired 2026-08-28 (it was the costliest runner). The Windows-compat code and the ASCII test-name guard remain, the maintainer's Windows 11 box runs found-issues and auto-fix every day, and a Windows regression report is welcome.
v3.10.5 — opt-in auto-fix and auto-sweep on top of the ledger;
actively developed and dogfooded (this repo's own ledger is maintained by
the plugin). End-to-end runtime probes exercise the generated statusline
shims against synthetic Claude Code stdin on every CI run, and stand-in
claude/codex/gh binaries drive the auto-fix flows in CI. Upgrading
from 2.x: docs/versioning.md.
Have a use case the plugin doesn't cover? Open an issue.
docs/architecture.md— how the pieces fit togetherdocs/format-spec.md— canonical entry formatdocs/modes.md— workflow modes and detectiondocs/deferring.md— defer lifecycle, recurrence detection, loop preventiondocs/configuration.md— every env-var opt-out and tunabledocs/versioning.md— SemVer rules + when to bump which segmentdocs/faq.md— common questions, including "how is this different from Linear / Jira / Backlog.md / claude-mem?"AGENTS.md— instructions for AI agents installing thisCONTRIBUTING.md— how to propose changesCHANGELOG.md— version history
Install fails with Permission denied (publickey)?
Claude Code's /plugin install currently shells out to git over SSH
for some marketplaces. Users without an SSH key set up for GitHub
will hit Permission denied (publickey) (even though
/plugin marketplace add worked — that fetch uses HTTPS).
Two paths forward:
- Set up SSH for GitHub. Run
gh auth setup-gitor follow GitHub's SSH key guide. - Refresh the marketplace. As of v1.2.0, the
altdoug-pluginsmarketplace metadata uses an explicit HTTPS clone URL. Re-run/plugin marketplace add AltDoug/claude-pluginsto pick up the updated source, then retry/plugin install found-issues.
Updates and uninstall
Auto-update (recommended). Run /plugin, open the Marketplaces
tab, pick altdoug-plugins, choose Enable auto-update. New versions
land silently at session start.
Manual update:
/plugin marketplace update altdoug-plugins
/plugin update found-issues
Uninstall — order matters. Run our cleanup before the platform
uninstall, or plugin-private state (statusline segment, /fi alias,
mode cache) will be orphaned in ~/.claude/:
/found-issues:uninstall # 1. plugin's own cleanup
/plugin uninstall found-issues # 2. platform uninstall
/plugin marketplace remove altdoug-plugins # 3. (only to remove the marketplace too)
Per-repo docs/found-issues.md files are intentionally preserved —
they're your project data.
Issues and PRs welcome. See CONTRIBUTING.md for the process. Quick PRs (typo fixes, small bugs) ship faster than big proposals — for those, please open an issue first to discuss the design.
MIT — see LICENSE.