claude-db
Project memory and a code-symbol graph for Claude Code, stored in your own SQLite, Postgres or MongoDB
Ticket, handover and lesson records kept in a repo's .story/ folder for Claude Code and Codex
By Story bloq TypeScript Local · stdio ProductivityKnowledge and memoryDeveloper tools
56 popularity score ★ 788 ↓ 67/wk
Opens the app, which asks before it adds the server.
npm install -g @storybloq/storybloq@latestclaude mcp add storybloq -- storybloq --mcp{
"mcpServers": {
"storybloq": {
"command": "storybloq",
"args": [
"--mcp"
]
}
}
}{
"mcpServers": {
"storybloq": {
"command": "storybloq",
"args": [
"--mcp"
]
}
}
}{
"servers": {
"storybloq": {
"type": "stdio",
"command": "storybloq",
"args": [
"--mcp"
]
}
}
}[mcp_servers.storybloq]
command = "storybloq"
args = ["--mcp"]gemini mcp add --scope user storybloq storybloq -- --mcpSTORYBLOQ_PROJECT_ROOT |
Optional: Folder holding .story/. Overrides walking up from the working directory (the old name CLAUDESTORY_PROJECT_ROOT is still read). |
|---|---|
STORYBLOQ_CLIENT |
Optional: Names the client. The docs set it to codex when registering with Codex. |
Storybloq gives Claude Code and Codex a project record that lives inside the repository: a .story/ folder of JSON and markdown files holding tickets, issues, roadmap phases, notes, lessons, design decisions (rulings) and session handovers. Because the files sit beside the code, they can be committed to Git and read by the next session, so an agent can pick up where the last one stopped instead of rebuilding context.
The MCP server is one part of the same npm package as the storybloq CLI, a client skill (/story in Claude Code, $story in Codex) and session hooks. Started with `storybloq --mcp`, it finds the project by walking up from the working directory to the nearest .story/config.json, or uses the folder named in STORYBLOQ_PROJECT_ROOT. Its tools read and edit the records, suggest the next ticket, write handovers, and drive an autonomous mode that walks a ticket through planning, plan review, tests, implementation, code review and finalizing. Further tool groups cover a local message bus between two agent sessions, duet arrangements with acceptance records, and multi-repo orchestration (federation).
Version 1.15.9, the latest on npm, registers 79 tools: 73 in src/mcp/tools.ts and six bus tools in src/mcp/bus-tools.ts. When no .story/ project is found it starts in a reduced mode with only storybloq_status, storybloq_session_guard and a storybloq_init tool that creates the project, then registers the rest (src/mcp/index.ts). The GitHub README lists glossary tools (storybloq_term_*) and ruling propose/accept/withdraw tools that are not in the 1.15.9 source.
The GitHub README now also describes a guided setup run by the CLI (setup-apply, setup-report, setup-verify) and priority and waiting-on fields for tickets and issues. Neither is in the 1.15.9 package README, and the ticket and issue tools in the 1.15.9 source take no priority or waiting-on input. The README says projects made by guided setup need CLI 1.16 or later, a version not yet on npm.
| Runtime | Node.js 20+ |
|---|---|
| Runs on | macOS, Windows, Linux |
| Also |
|
Install the package globally (`npm install -g @storybloq/storybloq@latest`) so `storybloq` is on PATH, then run `storybloq setup --client all` to register the server, the skill and the client hooks. The optional codex-bridge review backend that setup registers needs a Codex CLI login, or reviews fail.
Works on one project's .story/ records; it does not read your issue tracker or code host. Without a .story/ folder only three tools are offered until a project is created. Glossary (storybloq_term_*) and ruling propose/accept/withdraw tools named in the GitHub README are not in release 1.15.9. Autonomous code review stops after 12 rounds by default (recipeOverrides.stages.CODE_REVIEW.maxReviewRounds, 0 for no cap); three rounds past the cap the session ends with work left uncommitted. The makers say approval records do not guarantee correct code or replace tests and CI. Licensed under PolyForm Shield, which is source-available, not open source, and bars building a competing product.
Suits developers who run Claude Code or Codex across many sessions on one codebase and want plans, decisions and handovers stored as plain files in Git rather than in a hosted service. It runs locally and needs no account. It is less of a fit if your team already tracks work in GitHub Issues, Jira or Linear and wants the agent to use those, if you use an MCP client other than Claude Code or Codex (its skill and hooks target only those two), or if the source-available licence is a problem for your use.
34 only read, 24 change things, 2 can delete or overwrite. A ? marks an optional parameter.
storybloq_statusformat?: enumclientTaskId?: stringcompact?: booleanstorybloq_phase_liststorybloq_phase_currentstorybloq_phase_ticketsphaseId: stringnode?: stringstorybloq_phase_create changesid: stringname: stringlabel: stringdescription: stringsummary?: stringafter?: stringatStart?: booleanstorybloq_ticket_liststatus?: enumphase?: stringtype?: enumnode?: stringstorybloq_ticket_getid: stringformat?: enumwithActionability?: booleannode?: stringstorybloq_ticket_nextcount?: integernode?: stringstorybloq_ticket_blockednode?: stringstorybloq_ticket_create changestitle: stringtype: enumphase?: stringdescription?: stringblockedBy?: arrayparentTicket?: stringcitesRuling?: arraynode?: stringstorybloq_ticket_update changesid: stringstatus?: enumtitle?: stringtype?: enumorder?: integerdescription?: stringphase?: stringparentTicket?: stringblockedBy?: arraycrossNodeBlockedBy?: arrayforce?: booleancitesRuling?: arrayclearCitesRulings?: booleannode?: stringstorybloq_ticket_meta_getid: stringpath?: stringstorybloq_ticket_meta_set changesid: stringpath: stringvalue: anystorybloq_ticket_meta_unset deletesid: stringpath: stringstorybloq_issue_liststatus?: enumseverity?: enumcomponent?: stringphase?: stringnode?: stringstorybloq_issue_getid: stringformat?: enumwithActionability?: booleannode?: stringstorybloq_issue_create changestitle: stringseverity: enumimpact: stringcomponents?: arrayrelatedTickets?: arraylocation?: arraysourceRefs?: arraydedupeKey?: anycreatedBy?: stringphase?: stringcitesRuling?: arraynode?: stringstorybloq_issue_update changesid: stringstatus?: enumtitle?: stringseverity?: enumimpact?: stringresolution?: stringcomponents?: arrayrelatedTickets?: arraylocation?: arraysourceRefs?: arrayorder?: integerphase?: stringcitesRuling?: arrayclearCitesRulings?: booleannode?: stringstorybloq_issue_meta_getid: stringpath?: stringstorybloq_issue_meta_set changesid: stringpath: stringvalue: anystorybloq_issue_meta_unset deletesid: stringpath: stringstorybloq_note_liststatus?: enumtag?: stringstorybloq_note_getid: stringstorybloq_note_create changescontent: stringtitle?: stringtags?: arraystorybloq_note_update changesid: stringcontent?: stringtitle?: stringtags?: arraystatus?: enumstorybloq_lesson_liststatus?: enumtag?: stringsource?: enumstorybloq_lesson_getid: stringstorybloq_lesson_digestlimit?: integerselect?: arraystorybloq_lesson_create changestitle: stringcontent: stringcontext: stringsource: enumtags?: arraysupersedes?: stringstorybloq_lesson_update changesid: stringtitle?: stringcontent?: stringcontext?: stringtags?: arraystatus?: enumstorybloq_lesson_reinforce changesid: stringstorybloq_ruling_listscopeTag?: stringsuperseded?: booleanstorybloq_ruling_getid: stringstorybloq_ruling_create changestext: stringattribution: enumdate: stringscopeTags?: arraycites: arrayclientTaskId?: stringstorybloq_ruling_supersede changesid: stringwith?: stringtext?: stringattribution?: enumdate?: stringscopeTags?: arrayclientTaskId?: stringstorybloq_handover_liststorybloq_handover_latestcount?: integerbrief?: booleanpriming?: booleanformat?: enumstorybloq_handover_getfilename: stringformat?: enumstorybloq_handover_create changescontent: stringslug?: stringstorybloq_blocker_liststorybloq_snapshot changesstorybloq_recapstorybloq_recommendcount?: integernode?: stringstorybloq_exportphase?: stringall?: booleanstorybloq_validateformat?: enumintegrityOnly?: booleanstorybloq_selftest changesstorybloq_healthformat?: enumonly?: arrayrefresh?: booleanstorybloq_autonomous_guide changessessionId: stringaction: enumclientTaskId?: stringtakeover?: booleanownerGoneCandidateTakeover?: objectownerGoneCandidateCancel?: objectmode?: enumreviewEffort?: enumticketId?: stringtargetWork?: arrayreport?: objectstorybloq_review_lenses_prepare changesstage: enumdiff: stringchangedFiles: arrayticketDescription?: stringreviewRound?: integerpriorDeferrals?: arraysessionId?: stringtarget?: stringstorybloq_review_lenses_judgereviewVerdict: anyconvergenceHistory?: arraystorybloq_review_lenses_synthesize changesstage?: enumlensResults?: arrayactiveLenses: arrayskippedLenses: arrayreviewRound?: integerreviewId?: stringdiff?: stringchangedFiles?: arraysessionId?: stringcitedRulingsUndelivered?: objectstorybloq_session_reportsessionId: stringstorybloq_session_guardclientTaskId?: stringstorybloq_session_intelformat?: enumsessionId?: stringtranscript?: stringcallerModel?: stringfull?: booleanclientTaskId?: stringstorybloq_session_milestone changeskind: enumgateName?: stringnote?: stringclientTaskId?: stringstorybloq_register_subprocess changespid: integercmd: stringcategory: enumsessionId: stringstorybloq_roster_getformat?: enumall?: booleanstorybloq_arrangement_create changesbounds: arrayparties: arrayonIrreversibleWork: enumonReversibleWork?: enumstorybloq_arrangement_getid: stringformat?: enumstorybloq_arrangement_update changesid: stringlifecycle: enum