codebugs (Faxik)

代码错误

AI助手的持久代码查找、需求和发布跟踪器。 SQLite支持，通过MCP服务器+CLI公开。

AI助手在会话之间失去上下文。代码bug为代码审查结果、需求、依赖阻断器、并行代理协调和发布里程碑提供了持久的内存，并且令牌开销最小。

Session 1:  Review code → log 50 findings → forget them
Session 2:  summary → instant orientation → fix 20 → update status
Session 3:  pull_next → claim work → mark integrated → next agent picks up

没有上下文丢失。无需重新读取文件。没有象征性的重提。平行代理人不参加比赛。

为什么是代码bug

用人工智能助手构建一个真正的代码库会产生四个问题，随着时间的推移，这些问题会变得更加复杂：

1. 结果丢失了。 你花了2万个代币来审查一个文件，在聊天中记录了12个bug，而下一个会话根本不知道它们的存在。
2. 需求漂移。 REQUIREMENTS.md被手动编辑，被遗忘，与代码相矛盾，没有人抓住它。
3. 平行代理竞争。 两个代理都选择了相同的bug，都编辑了相同的文件，都认为自己已经发布了它。
4. 释放失去了对其中内容的跟踪。 工作被困在特色树枝上长达9天。“我们在1.1上的位置在哪里？”没有单一的答案。

codebugs是一个SQLite数据库(.codebugs/findings.db)这就解决了这四个问题。8个独立模块、59个MCP工具、1个CLI。

安装

# Global install (recommended)
pipx install codebugs

# Or with pip/uv
pip install codebugs

设置

克劳德代码（MCP）

添加 ~/.claude.json （全球）或 .mcp.json （每个项目）：

{
  "mcpServers": {
    "codebugs": {
      "command": "codebugs-mcp"
    }
  }
}

数据库位于 .codebugs/findings.db 在当前工作目录中，每个项目都有自己的。添加 .codebugs/ 致你的 .gitignore.

独立运行模块

使用 --mode 只加载您需要的工具：

{
  "mcpServers": {
    "codebugs": {
      "command": "codebugs-mcp",
      "args": ["--mode", "findings"]
    }
  }
}

CLI采用相同的标志： codebugs --mode findings summary.

其他MCP客户端

任何兼容MCP的客户端都可以连接到 codebugs-mcp 通过stdio传输。

八个模块

模块是自注册的——添加新模块是在其自己的文件本地进行的。看 docs/superpowers/specs/ 建筑史。

快速浏览

发现——记录下来，永远不要重新发现

MCP工具：

CLI：

codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42"
codebugs summary
codebugs query --status open --severity critical
codebugs update CB-1 --status fixed --notes "Fixed in PR #42"
codebugs categories

当添加新发现时 里程碑自动路由器 自动将其附加到 stream/triage （或 stream/security 当 severity=critical 和 category 以...开始 security:).该发现及其分诊条目属于同一交易。

要求——核实发货内容，表面矛盾

MCP工具：

CLI：

codebugs reqs-import REQUIREMENTS.md
codebugs reqs-summary
codebugs reqs-verify
codebugs reqs-query --status Implemented --priority Must
codebugs reqs-update FR-090 --status Superseded --notes "Replaced by vault architecture"
codebugs reqs-export REQUIREMENTS.md

阻止程序——“X被Y阻止”，自动解除阻止

MCP工具：

触发器有三种类型： entity_resolved （等待另一个发现/要求达到终端状态）， date （在特定日期时间解除阻塞），以及 manual （操作员信号）。当你标记一个发现时 fixed，每一个等待它的阻断器都会自动解除阻断，并在下一个阻断器中浮出水面 blockers_check.

里程碑——释放容器+固定流+容量感知拉取

MCP工具：

自动创建四个种子里程碑：

• stream/triage --未排序结果的收件箱（默认目的地）
• stream/maintenance --延期/童子军工作
• stream/security --紧急修复（抢先发布工作）
• release/1.1 --1.0之后的首次发布

pull_next 优先级顺序： stream/security > release/* （最早 target_date 第一）> stream/triage > stream/maintenance在一个里程碑内：优先ASC，然后 created_at ASC。

资格： 项目是 open，无活性阻断剂（跳过 item_kind='external')，需要验收 size='large'，并且必须声明发布里程碑中的一个大错误 linked_frs 其id解析为中的行 requirements来自多个代理的并发调用是原子性的——声明通过以下方式序列化 BEGIN IMMEDIATE.

CLI：

codebugs milestone-list
codebugs milestone-status release/1.1
codebugs triage-inbox
codebugs wip-status
codebugs milestone-audit --milestone release/1.1

一个典型的自主代理循环：

# 1. Agent claims the next eligible item.
item = pull_next(agent_id="agent-A", capacity={"large": 1, "small": 2, "triage": 5})

# 2. (Optional) flag a feature branch.
mark_branch_only(item_ref=item["item_ref"], branch_name="feat/CB-1234")

# 3. After integration, mark it done with the commit SHA.
mark_integrated(item_ref=item["item_ref"], commit="abc123…")

# 4. Free the agent's capacity slot.
release_item(item_ref=item["item_ref"], status="done")

关闭释放运行关闭门：未完成、仅分支和阻断门项目拒绝让里程碑发货。 force=True （有记录的原因）覆盖——但是 stream/* 里程碑 不能 即使用力，也要关闭。

扫描——具有递归感知生命周期的批量迭代

MCP工具：

codebugs sweep-create --name lint-pass --batch-size 5
codebugs sweep-add lint-pass src/*.py --tags critical
codebugs sweep-next lint-pass
codebugs sweep-mark lint-pass src/api.py
codebugs sweep-status lint-pass

具有自定义生命周期（例如用于追溯发现）：

codebugs sweep-create --name retro-findings \
    --lifecycle DETECTED,CONFIRMED,ESCALATED,RESOLVED,DROPPED \
    --terminal-states RESOLVED,DROPPED
codebugs sweep-add retro-findings finding-2026-04-todo-bypassed --tags silent_abandonment
codebugs sweep-mark retro-findings finding-2026-04-todo-bypassed --state CONFIRMED
codebugs sweep-archive-items retro-findings --state RESOLVED --older-than 30d

工作台--随时间变化的性能快照

MCP工具：

Merge--并行代理合并序列化

MCP工具：

运作原理

问题

人工智能代码审查会议产生的结果会丢失。多个代理并行进行双索赔工作。需求文件漂移。释放失去了对其中内容的跟踪。

解决方案

codebug将所有内容存储在一个本地SQLite数据库中。人工智能助手在发现结果、需求和里程碑项目时将其写入，然后在未来的会话中查询数据库以进行即时上下文恢复。并发代理通过同一数据库进行协调——没有竞争条件，原子声明。

代币节省A. summary 调用返回约200个令牌的结构化JSON概述。如果没有代码错误，重建相同的上下文需要花费2K-10K+的文件读取和对话历史令牌。

典型工作流程

代码审查循环:

1. AI审查代码，调用 categories 为了命名的一致性，那么 add 对于每一个发现。
2. 每 add 自动将发现路由到 stream/triage.
3. 下一节：人工智能通话 summary → 50 公开调查结果→ query --severity critical → 修复最坏的情况→ update CB-N --status fixed.
4. 随着时间的推移， categories 揭示系统性问题——“12 tz_naive_datetime 已修复9个文件→ 是时候制定皮棉规则了。"

释放循环:

1. 分类：人工智能呼叫 triage_inbox → triage_dismiss 无缺陷， triage_promote 真实物品 release/1.1 （与 linked_frs 对于需要FR行的那些）。
2. 执行：每个并行代理调用 pull_next(agent_id=..., capacity=...) → 领取下一个符合条件的物品。
3. 着陆后： mark_integrated(item, commit) → release_item(item, status='done').
4. 关闭： milestone_close("release/1.1").如果树枝上有东西搁浅，拒绝；列出违规者及其分支机构名称。

模式（突出显示）

所有桌子共享 .codebugs/findings.db 具有灵活的JSON列。模式是累加的——每个模块都拥有自己的表，声明依赖关系，并以累加的方式迁移。

研究结果

需求

里程碑

项目种类有 bug （根据验证 findings), requirement （根据验证 requirements)，或 external （自由形式，跳过拦截器）。这 (milestone_id, item_kind, item_ref) 独特的约束可防止双重附着。

阻塞器

清扫

杀手级功能

随时间变化的模式检测

$ codebugs categories
category                        total  open  fixed
tz_naive_datetime                  15     3     12
n_plus_one                          8     2      6
missing_input_validation            6     4      2

如果你一直固定同一个类别→ 是时候制定皮棉规则了。代码bug将被动的bug修复转化为主动的预防。

需求验证

reqs_verify 在文档发货前发现其腐烂：

$ codebugs reqs-verify
Verified 683 requirements.

12 issue(s) found:
check   sev       id      message
tests   high      FR-350  Test file not found: test_entity_graph.py
status  high      FR-090  Description mentions 'superseded' but status is 'Planned'
status  medium    FR-006  Must-priority requirement implemented without test coverage
ids     medium    --      Numbering gaps (5+): FR-025..FR-029, FR-316..FR-329

语义需求搜索

存储嵌入（调用方通过任何嵌入API生成向量），并从语义上查找相关需求：

reqs_embed(req_id="FR-001", embedding=[0.1, 0.2, ...])
reqs_search_similar(query_embedding=[...], limit=5, min_similarity=0.3)

SQLite中的Float32-BLOB存储；强力余弦相似性——快速满足数千种需求。

关门执法

milestone_close("release/1.1") 不会让你发布一个工作滞留在分支上的版本：

$ codebugs milestone-status release/1.1
release/1.1  (release, state=open)
  target: 2026-06-15 (35 days)

Items: 12 total (3 open/in_progress, 9 done)
  Branch-only: CB-1234
  Blocked: CB-1240

当您尝试关闭它时：

ValueError: cannot close release/1.1: unfinished items (3): CB-1234, CB-1240, CB-1242;
            branch-only items (1): CB-1234@feat/CB-1234;
            items with active blockers (1): CB-1240
            (use force=True with reason to override)

溪流(stream/*)根本拒绝关闭——它们是永久性的桶。

需求

• Python 3.11+
• 除此之外没有外部运行时依赖关系 mcp>=1.0.0 （对于服务器）
• SQLite（与Python捆绑在一起）

发展

# Run tests
uv run python -m pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

看 CLAUDE.md 建筑规则和惯例。

许可证

麻省理工学院