codebugs MCP server
2026년 10월 30일 커밋중복 제거 기능이 있는 SQLite 기반 시스템을 통해 AI 어시스턴트가 코드 결함, 요구 사항 및 릴리스를 추적합니다.
다른 이름 faxik/codebugs
- 스타
- 1
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 30일
- 라이선스
- MIT
codebugs MCP란?
codebugs은(는) MCP server입니다. 중복 제거 기능이 있는 SQLite 기반 시스템을 통해 AI 어시스턴트가 코드 결함, 요구 사항 및 릴리스를 추적합니다.
프로젝트 README에서 생성된 요약
codebugs MCP server 정보
이 SQLite 기반 시스템을 사용하면 AI 어시스턴트가 코드 결함, 요구 사항 및 릴리스를 더욱 체계적으로 관리할 수 있습니다. 모든 보고에 대해 새로운 항목을 생성하는 일반적인 트래커와 달리, 이 도구는 동일한 이슈가 반복적으로 발견될 경우 이를 단일 결함에 대한 관찰로 처리합니다. 이를 통해 발생 횟수를 높이거나 새로운 보고가 더 심각한 문제를 나타낼 때 심각도를 높임으로써 중복된 노이즈를 방지합니다. 또한 새로운 항목을 만드는 대신 기존 카드를 다시 열어 회귀(regression)를 추적하므로 버그의 전체 이력이 하나의 행에 유지됩니다.
개발자는 CLI를 통해 사용하거나 Claude Code와 같은 클라이언트를 위한 MCP server로 사용할 수 있습니다. 이 시스템에는 편집으로 인해 이동한 코드를 추적하는 anchor_resolve 및 여러 에이전트가 동시에 동일한 작업을 수행하는 것을 방지하는 claims_claim과 같은 특화된 기능이 포함되어 있습니다. 로컬 사용을 위해 설계되었으며, init 명령으로 프로젝트별 초기화를 수행하여 findings.db 파일을 생성해야 합니다. 사용자는 사용 가능한 도구 세트를 제한하기 위해 서버를 findings와 같은 특정 모듈로 제한할 수도 있습니다.
활용 사례
- 1중복 버그 보고 방지시스템이 후속 보고를 동일한 결함에 대한 관찰로 처리하므로, AI 에이전트가 버그를 여러 번 보고하더라도 데이터베이스가 지저분해지지 않습니다.
- 2편집 후 코드 이동 추적주변 코드가 리팩터링되거나 다른 라인 번호로 이동한 후에도 개발자가 버그 위치를 찾을 수 있습니다.
- 3여러 AI 에이전트 협업 조율두 개의 서로 다른 AI 어시스턴트가 동시에 동일한 결함을 수정하려고 시도하는 것을 방지할 수 있습니다.
- 4소프트웨어 회귀 식별이전에 수정된 버그가 다시 나타나면 시스템은 이를 원래의 결함 카드에 회귀로 기록합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
구성
CODEBUGS_ROOT
| 이름 | 설명 | 유형 |
|---|---|---|
| CODEBUGS_ROOT | — |
자동 검사
2026년 11월 15일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능faxik/codebugs is public and reachablegithub.com/faxik/codebugs ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-30github.com/faxik/codebugs ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기codebugs
A code-finding, requirements, and release tracker for AI assistants — one where a finding has an identity. SQLite-backed, exposed via an MCP server and a CLI.
Most trackers treat every report as a new row, so the second agent to notice the same bug files it again, and the queue fills with copies of one defect. codebugs treats a finding as a defect, and each report of it as one observation of that defect:
$ codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42" --new-category
Added: CB-1
$ codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42"
Bumped: CB-1 (occurrence 2)
$ codebugs update CB-1 --status fixed
Updated: CB-1 (status=fixed, severity=high)
$ codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42"
Reopened as regression: CB-1 (occurrence 3)
One card, three observations, and a regression recorded on the row it belongs to. Filing an observation again is normal and useful, not noise.
What makes this different
Deduplication is the point, not a side effect — and the rest of the design falls out of that one decision.
- Filing the same finding twice does not create two cards. The second report bumps the first: its occurrence count goes up, and its severity rises if this sighting was worse than the last. Severity only ever escalates under observation, so a card filed
lowand re-seencriticalstops hiding from a--severity criticalquery. Lowering it back is a deliberateupdate, never an accident of the last report. - A card that was fixed and comes back is a regression, not a duplicate. Re-filing reopens the same card and records the regression on it, so one defect's whole history stays on one row.
- A decision stays decided. Re-filing something already dismissed as
wont_fixornot_a_bugdoes not quietly reopen the argument. It files a new card pointing back at the dismissal, so the recurrence is visible and the original ruling survives. - The place in the code outlives the edit. When a report names a line range, the location is anchored at filing time from git. After the file is edited around it,
anchor_resolvereports where that code went —moved, with the new line numbers — instead of pointing at whatever now occupies the old line. - Parallel agents don't collide.
claims_claimgives one agent a card and refuses the second, naming who holds it and from which repo, so two agents cannot silently fix the same thing. Closing a card releases the claim in the same transaction. - Findings can be related and grouped. Cards link to each other, and a similarity report proposes families of near-duplicate findings as a dry run you inspect before merging anything.
- It tells you when it could not look. A tracker it cannot read, a file it cannot stat, an anchor whose card never named a code span — each of these comes back as undetermined, with the reason, rather than as a confident wrong answer.
codebugs wherewill tell you which tracker a command is actually bound to and which channel decided that, because a binding you cannot see is a binding you cannot debug.
Underneath that, it is durable memory across sessions: findings survive the conversation that produced them, requirements are checked against the code that claims to implement them, blocked work resurfaces when its dependency resolves, and a release knows what is still stranded on a branch.
codebugs is one SQLite database (.codebugs/findings.db). Modules are self-registering, and the running server reports its own tool catalogue — the module table below is the set of them.
Install
codebugs is not published to PyPI. There is nothing under that name in the public index, so
pipx install codebugs and pip install codebugs cannot resolve — they fail before they start.
Install it from a clone instead, by path:
git clone https://github.com/faxik/codebugs.git
pipx install ./codebugs # global install, recommended
pip install ./codebugs works too, into whatever environment is active.
Two consequences of installing by path, both worth knowing before the first surprise:
- The installed copy is a snapshot, not a link. Editing the clone afterwards does not change
what
codebugsruns. Re-runpipx install --force ./codebugsto pick the changes up, or pass--editableat install time if you want the clone itself to be what runs. - The installer resolves dependencies on its own and does not read this repository's
uv.lock. So the versions you end up running are whatever your installer resolved — for a freshpipxinstall, typically the newest release each declared range admits; forpipinto an environment that already has a satisfying version, whatever was already there — and neither is necessarily the combination the test suite ran against. That gap is real and has bitten once already, which is why thenewest-sdkjob in.github/workflows/ci.ymlruns the whole suite against the newest versions the ranges admit. Note what that buys and what it does not: a break on the versions you would install becomes VISIBLE there instead of passing silently on the locked ones — it is not a promise that the newest combination currently works.
Setup
Create the tracker
Run this once per project, in the project root:
codebugs init
This creates .codebugs/findings.db. init is the only command that creates the .codebugs/ directory — every other command discovers an existing one by walking up from the current directory (unless you point it somewhere explicitly, see below), and refuses with an actionable error if there is none. That refusal is deliberate: silently creating an empty database is how findings go missing.
There is one deliberate exception, and it is worth stating precisely because it looks like the rule being broken. The upward walk treats an existing .codebugs/ directory as the opt-in, so if that directory is there but holds no findings.db, the next command creates the database inside it rather than refusing. The common way to end up in that state is an interrupted init — the directory is created before the database — and self-healing on the next command is more useful there than demanding a second init.
A tracker you name explicitly is held to the stricter rule. --repo, --tracker-root and $CODEBUGS_ROOT must resolve to a directory that actually contains findings.db; a .codebugs/ without one is refused, and the message names which channel pointed there. The difference is about evidence: standing inside a directory says something about where you are, while a named path is an assertion that can be mistyped, or exported into a shell days ago and inherited by an unrelated process. That is exactly where a silent empty tracker does the most damage.
Two consequences worth knowing:
-
Run
initat the project root, not in a subdirectory. Discovery binds to the nearest.codebugs/, so a nested tracker hides the project's real one from everything beneath it.initrefuses to do this unless you pass--force. -
Git worktrees share the main repo's tracker. A worktree's
.gitis a file pointing at the main repo, which discovery follows — so findings filed from a worktree land in the project's database, not in a throwaway that dies with the worktree.initrefuses to run inside a worktree for the same reason; run it in the main checkout.Two layouts are the exception: if the main repo is bare or was created with
--separate-git-dir, git records no path back to a main checkout — its owngit worktree listreports the git directory instead. Discovery usually refuses those with an explicit error rather than guessing. There is one case it cannot detect: a--separate-git-dirrepo whose git directory is itself named.gitlooks exactly like a normal checkout, so discovery binds to the directory holding the git dir instead of the real checkout, silently. Nothing local can distinguish the two — git reports that directory as a valid work tree as well — so the remedy is to state the root explicitly (below). Runinitin the main checkout before creating worktrees.
Pointing codebugs at a specific tracker
Discovery is a heuristic, so it has an override:
codebugs --tracker-root /path/to/project query # this invocation only
export CODEBUGS_ROOT=/path/to/project # this shell and anything it spawns
Resolution order, most specific first: a command's own explicit path argument (--repo, where a command has one) → --tracker-root → CODEBUGS_ROOT → walking up from the current directory. A per-command argument outranks a declaration because it names one operation's target, while a declaration is process-wide.
codebugs where # show the current binding and which channel decided it
where is a diagnostic, not a precedence level: it prints the resolved root, the database path, and the channel — the fastest way to check that a command is about to read the tracker you think it is.
One thing is true of every declared root, for every command except init: a root that contains no .codebugs/ is a hard error, never a new tracker. The value may be a stale export inherited from another shell, and silently creating an empty database there is how findings go missing.
init is the exception, and it treats the two channels differently, because they carry different evidence. --tracker-root DIR init creates the tracker in DIR — the flag is typed on the command line being run, so it is an assertion about this invocation, exactly like a path argument. CODEBUGS_ROOT is ignored by init, which creates where you are standing, and warns that later commands will read somewhere else: an environment variable exported days ago and inherited by an unrelated process must never conjure a tracker in a directory you are not in. Whenever the tracker init created is not the one the next command would read, it says so on stderr, since otherwise it would report success for a dead end.
CODEBUGS_ROOT is inherited by every subprocess, so export it only when you mean "this shell works on that project". For one-off use across projects, prefer --tracker-root.
Claude Code (MCP)
Add to ~/.claude.json (global) or .mcp.json (per-project):
{
"mcpServers": {
"codebugs": {
"command": "codebugs-mcp"
}
}
}
The database lives at .codebugs/findings.db, discovered by walking up from the server's working directory — each project gets its own. Run codebugs init in the project first (see above), or every tool call will fail with "no .codebugs/ found".
The server connects lazily, per tool call, so it starts successfully even when no tracker is reachable. At startup it writes a diagnostic to stderr — which MCP clients log — if discovery failed, or if a root was declared rather than discovered; on the ordinary path it says nothing. It never refuses to start: a project directory that appears later must still work.
To pin one server to one tracker instead of deriving it from the working directory:
{
"mcpServers": {
"codebugs": {
"command": "codebugs-mcp",
"args": ["--tracker-root", "/path/to/project"]
}
}
}
Only do this when you want that server bound to a single project — the default cwd-derived behavior is what lets one registration serve many. Add .codebugs/ to your .gitignore.
Running Modules Independently
Use --mode to load only the tools you need:
{
"mcpServers": {
"codebugs": {
"command": "codebugs-mcp",
"args": ["--mode", "findings"]
}
}
}
Any module name from the module table below is a valid mode, and all — the default — loads everything. The CLI takes the same flag: codebugs --mode findings summary.
One asymmetry is worth knowing before you rely on it: usage is a CLI-only mode. It registers a command but no MCP tools, so codebugs --mode usage usage works, while codebugs-mcp --mode usage does not start at all — the server does not accept that value, and refuses it with argument --mode: invalid choice: 'usage' and exit code 2. It is not a server that runs with an empty catalogue; there is no server. The two lists of accepted modes are compared with each other, and with the module table below, by the test suite — so a mode that appears on one surface and not the other turns a test red rather than surprising you here.
Other MCP Clients
Any MCP-compatible client can connect to codebugs-mcp via stdio transport.
The modules
Every name in this table is a valid --mode value.
| Module | Domain | Headline tools |
|---|---|---|
| findings | Bugs, tech-debt, review findings | summary, add, query, categories |
| reqs | Functional requirements (FR-N) | reqs_summary, reqs_add, reqs_verify, reqs_search_similar |
| blockers | "X is blocked by Y" dependency graph | blockers_add, blockers_check |
| sweep | Batch iteration with state machines | codesweep_create, codesweep_next, codesweep_mark |
| bench | Performance benchmark snapshots | codebench_import, codebench_query |
| merge | Parallel-agent merge serialization | codemerge_start, codemerge_claim |
| milestones | Releases, streams, capacity-aware pull | pull_next, milestone_status, milestone_close |
| provenance | Staleness vs git history, commit trailers | staleness_check |
| claims | Which agent holds a finding or requirement | claims_claim, claims_release, claims_who_holds |
| loc | Where in the code a finding is, across edits | anchor_resolve, anchor_recapture |
| similarity | Near-duplicate findings, as a dry run | similarity_check, similarity_report |
| relations | Typed, retractable links between findings | relations_relate, relations_query |
| grouping | Reads the axes the tracker stores but never exposed | grouping_citations, grouping_tags, grouping_filing |
| usage | Tool-call counters (CLI only — no MCP tools) | — |
Modules are self-registering — adding a new one is local to its own file. See docs/superpowers/specs/ for the architecture history.
Not every MCP tool has a CLI verb. The milestones module is where the gap is widest: milestone_create, milestone_update, milestone_add_item, milestone_move_item, milestone_set_status, milestone_defer, milestone_close, triage_dismiss, triage_promote, pull_next and release_item are reachable through MCP only. From a terminal you can inspect a release, but you cannot create one or pull work from it.
Quick tour
Findings — log it, never re-discover it
MCP tools:
| Tool | Purpose |
|---|---|
summary |
Dashboard overview — start here for orientation |
add |
File an observation. Creates, bumps, reopens or refiles — read dedup_action to see which |
batch_add |
File several observations at once |
update |
Change status, severity, notes, tags or metadata (append_note adds, notes replaces) |
query |
Search/filter with pagination and group-by |
get |
Fetch one finding by id, with its full body and occurrence history |
recent |
Findings touched at or after a date — the one call for "what closed since" |
stats |
Cross-tabulated counts (severity x category/file/status) |
categories |
List existing categories — call before add for consistency |
categories_normalize |
Fold twin category spellings together. Dry run by default |
staleness_check lives in the provenance module rather than here, and anchor_resolve in loc; both are listed in the module table. The tools behind the opening section — anchors, similarity, relations and grouping — have their own entry under Identity, location and grouping below.
CLI:
codebugs add -s high -c n_plus_one -f src/api.py -d "Query in loop at line 42" --new-category
codebugs summary
codebugs query --status open --severity critical
codebugs update CB-1 --status fixed --append-note "Fixed in PR #42"
codebugs categories
--new-category is needed the first time a category is used, and only then. A category the tracker has never seen is refused, naming the closest existing spellings, because the common way a category set fragments is a typo — n-plus-one beside n_plus_one — and a fragmented category set is what makes categories stop revealing patterns. Once n_plus_one exists, later findings use it without the flag. Spelling is normalized on the way in, so hyphens, spaces and case do not mint twins.
--append-note adds to a finding's notes; --notes replaces them wholesale. Prefer --append-note when recording investigation history — --notes will discard whatever was there, which is usually not what you want on a finding others have been working.
When a new finding is added, the milestones auto-router automatically attaches it to stream/triage (or stream/security when severity=critical and category starts with security:). The finding and its triage entry land in the same transaction.
Requirements — verify what shipped, surface contradictions
MCP tools:
| Tool | Purpose |
|---|---|
reqs_summary |
Requirements dashboard — start here |
reqs_add |
Add a requirement (FR-001, priority, status, test coverage) |
reqs_update |
Change status, description, priority, test coverage |
reqs_query |
Search/filter by status, priority, section, free text |
reqs_get |
Fetch a single requirement by ID with full body |
reqs_stats |
Cross-tabulated counts (status x priority) |
reqs_verify |
Automated checks: ghost test files, duplicate IDs, status contradictions |
reqs_import |
Import from REQUIREMENTS.md (parses markdown tables) |
reqs_embed / reqs_batch_embed |
Store embedding vectors |
reqs_search_similar |
Semantic search across requirements |
reqs_embedding_stats |
Report on embedding coverage |
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
Blockers — "X is blocked by Y", with auto-unblock
MCP tools:
| Tool | Purpose |
|---|---|
blockers_add |
Defer an item until another item resolves, a date passes, or a manual signal |
blockers_query |
List blockers filtered by item, dependency, trigger type |
blockers_check |
Find currently-actionable items (all blockers satisfied) |
blockers_resolve |
Cancel or manually resolve a blocker |
Triggers come in three flavors: entity_resolved (waits for another finding/requirement to reach a terminal state), date (unblocks on a specific datetime), and manual (operator signal). When you mark a finding fixed, every blocker that was waiting on it auto-unblocks and surfaces in the next blockers_check.
Milestones — release containers + standing streams + capacity-aware pull
MCP tools:
| Tool | Purpose |
|---|---|
milestone_status |
Rollup for one milestone (counts by status/size, branch-only, blocked, days to target) |
milestone_list |
List milestones, filter by kind / state |
milestone_create |
Create a release or stream |
milestone_update |
Mutate description, target_date, state |
milestone_add_item |
Attach a bug / requirement / external ref to a milestone |
milestone_move_item |
Move an item between milestones |
milestone_set_status |
Open / in_progress / done / dismissed / deferred |
milestone_defer |
Move to stream/maintenance with status='deferred' |
milestone_close |
Refuses if open / branch-only / blocked items remain (force overrides, except for streams) |
milestone_audit_query |
Full state-transition history |
triage_inbox |
Items waiting to be triaged |
triage_dismiss |
Reject a triage item; propagates to underlying entity |
triage_promote |
Move a triage item to a target milestone |
pull_next |
Atomically claim the next eligible item for the calling agent |
release_item |
Free agent capacity (status='done' or 'abandoned') |
wip_status |
Snapshot of agent_capacity per agent |
mark_branch_only |
Flag an item as living on a feature branch only |
mark_integrated |
Mark merged-to-main with commit SHA; clears branch_only |
Four seed milestones are created automatically:
stream/triage— inbox for unsorted findings (default destination)stream/maintenance— deferred / boy-scout workstream/security— urgent fixes (preempts release work)release/1.1— first post-1.0 release
pull_next priority order: stream/security > release/* (earliest target_date first) > stream/triage > stream/maintenance. Within a milestone: priority ASC, then created_at ASC.
Eligibility: item is open, no active blockers (skipped for item_kind='external'), acceptance required for size='large', and a large bug in a release milestone must declare linked_frs whose ids resolve to rows in requirements. Concurrent calls from multiple agents are atomic — claims are serialized via 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
A typical autonomous-agent loop:
# 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")
Closing a release runs the close-gate: unfinished, branch-only, and blocker-gated items refuse to let the milestone ship. force=True (with a logged reason) overrides — but stream/* milestones cannot be closed, even with force.
Sweeps — batch iteration with recurrence-aware lifecycles
MCP tools:
| Tool | Purpose |
|---|---|
codesweep_create |
Create a new sweep (optional lifecycle=[...], terminal_states=[...], transitions={...} for state machines) |
codesweep_add |
Add items. Atomic upsert: existing items bump recurrence_count, refresh last_seen, un-archive |
codesweep_next |
Next batch of unprocessed (non-terminal, non-archived) items |
codesweep_mark |
Transition state (legacy processed=True still works) |
codesweep_status |
Progress overview |
codesweep_archive / codesweep_archive_items |
Soft-delete |
codesweep_list_items / codesweep_list |
Inspection |
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
With a custom lifecycle (e.g. for retro findings):
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
codebugs MCP 질문
codebugs는 중복된 버그 보고를 어떻게 처리하나요?
동일한 이슈에 대한 여러 보고를 단일 결함에 대한 관찰로 처리합니다. 새로운 항목을 생성하는 대신 발생 횟수를 늘리고 심각도를 높입니다.
트래커는 코드 변경 및 라인 번호 이동을 어떻게 처리하나요?
git-anchored 위치를 사용하여 편집 후에도 코드를 추적합니다. anchor_resolve 도구를 통해 코드 블록이 새로운 라인 번호로 이동했는지 확인할 수 있습니다.
여러 AI 에이전트가 동시에 동일한 버그를 작업할 수 있나요?
네, 한 번에 하나의 에이전트만 특정 카드를 보유하도록 보장하는 claim 메커니즘을 사용하여 충돌을 방지합니다.