Storybloq

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

Connect your client

Local (npm)

Add in one click

Opens the app, which asks before it adds the server.

Or add it by command or config

FirstTerminal
npm install -g @storybloq/storybloq@latest
Claude CodeTerminal
claude mcp add storybloq -- storybloq --mcp
Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "storybloq": {
      "command": "storybloq",
      "args": [
        "--mcp"
      ]
    }
  }
}
Cursor~/.cursor/mcp.json
{
  "mcpServers": {
    "storybloq": {
      "command": "storybloq",
      "args": [
        "--mcp"
      ]
    }
  }
}
VS Code.vscode/mcp.json
{
  "servers": {
    "storybloq": {
      "type": "stdio",
      "command": "storybloq",
      "args": [
        "--mcp"
      ]
    }
  }
}
Codex~/.codex/config.toml
[mcp_servers.storybloq]
command = "storybloq"
args = ["--mcp"]
Gemini CLITerminal
gemini mcp add --scope user storybloq storybloq -- --mcp

Settings 2

STORYBLOQ_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. For Codex.

What it does

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.

What it needs

RuntimeNode.js 20+
Runs onmacOS, Windows, Linux
Also
  • Claude Code, or Codex CLI 0.130.0 or newer
  • A project with a .story/ folder (storybloq init or the storybloq_init tool)

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.

Limits

  • Not covered Works on one project's .story/ records. It does not read your issue tracker or code host.
  • Limit With no .story/ folder found, only storybloq_status, storybloq_session_guard and storybloq_init are offered until a project is created.
  • Limit Glossary tools (storybloq_term_*) and ruling propose, accept and withdraw tools named in the GitHub README are not in release 1.15.9.
  • Early release Guided setup (setup-apply, setup-report, setup-verify) and the --priority and --waiting-on flags are in the GitHub README but not in 1.15.9. Projects made by guided setup need CLI 1.16.
  • Platform In the guided setup the README describes, the build and verify stages are unsupported on Windows, and verify needs lsof.
  • Limit Autonomous code review caps at 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.
  • Limit The makers say review and approval records do not guarantee correct code or replace tests, CI and release checks.
  • Limit Licensed under PolyForm Shield 1.0.0: source-available, not OSI open source, and it bars building a competing product.

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.

Who it suits

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.

Tools 60 of 79

34 only read, 24 change things, 2 can delete or overwrite. A ? marks an optional parameter.

storybloq_status
Summarises the project: phases, counts and open risksformat?: enumclientTaskId?: stringcompact?: boolean
storybloq_phase_list
Lists roadmap phases
storybloq_phase_current
Shows the phase now in progress
storybloq_phase_tickets
Lists the tickets in one phasephaseId: stringnode?: string
storybloq_phase_create changes
Adds a roadmap phaseid: stringname: stringlabel: stringdescription: stringsummary?: stringafter?: stringatStart?: boolean
storybloq_ticket_list
Lists tickets, with filtersstatus?: enumphase?: stringtype?: enumnode?: string
storybloq_ticket_get
Reads one ticketid: stringformat?: enumwithActionability?: booleannode?: string
storybloq_ticket_next
Picks the highest-priority ticket to work oncount?: integernode?: string
storybloq_ticket_blocked
Lists tickets held up by othersnode?: string
storybloq_ticket_create changes
Creates a tickettitle: stringtype: enumphase?: stringdescription?: stringblockedBy?: arrayparentTicket?: stringcitesRuling?: arraynode?: string
storybloq_ticket_update changes
Changes a ticket's fields or statusid: stringstatus?: enumtitle?: stringtype?: enumorder?: integerdescription?: stringphase?: stringparentTicket?: stringblockedBy?: arraycrossNodeBlockedBy?: arrayforce?: booleancitesRuling?: arrayclearCitesRulings?: booleannode?: string
storybloq_ticket_meta_get
Reads custom metadata on a ticketid: stringpath?: string
storybloq_ticket_meta_set changes
Sets a custom metadata key on a ticketid: stringpath: stringvalue: any
storybloq_ticket_meta_unset deletes
Removes a custom metadata key from a ticketid: stringpath: string
storybloq_issue_list
Lists recorded issuesstatus?: enumseverity?: enumcomponent?: stringphase?: stringnode?: string
storybloq_issue_get
Reads one issueid: stringformat?: enumwithActionability?: booleannode?: string
storybloq_issue_create changes
Records a new issuetitle: stringseverity: enumimpact: stringcomponents?: arrayrelatedTickets?: arraylocation?: arraysourceRefs?: arraydedupeKey?: anycreatedBy?: stringphase?: stringcitesRuling?: arraynode?: string
storybloq_issue_update changes
Changes an issueid: stringstatus?: enumtitle?: stringseverity?: enumimpact?: stringresolution?: stringcomponents?: arrayrelatedTickets?: arraylocation?: arraysourceRefs?: arrayorder?: integerphase?: stringcitesRuling?: arrayclearCitesRulings?: booleannode?: string
storybloq_issue_meta_get
Reads custom metadata on an issueid: stringpath?: string
storybloq_issue_meta_set changes
Sets a custom metadata key on an issueid: stringpath: stringvalue: any
storybloq_issue_meta_unset deletes
Removes a custom metadata key from an issueid: stringpath: string
storybloq_note_list
Lists project notesstatus?: enumtag?: string
storybloq_note_get
Reads one noteid: string
storybloq_note_create changes
Adds a notecontent: stringtitle?: stringtags?: array
storybloq_note_update changes
Edits a noteid: stringcontent?: stringtitle?: stringtags?: arraystatus?: enum
storybloq_lesson_list
Lists recorded lessonsstatus?: enumtag?: stringsource?: enum
storybloq_lesson_get
Reads one lessonid: string
storybloq_lesson_digest
Returns a ranked summary of lessons for contextlimit?: integerselect?: array
storybloq_lesson_create changes
Records a lesson learnedtitle: stringcontent: stringcontext: stringsource: enumtags?: arraysupersedes?: string
storybloq_lesson_update changes
Edits a lessonid: stringtitle?: stringcontent?: stringcontext?: stringtags?: arraystatus?: enum
storybloq_lesson_reinforce changes
Marks a lesson as confirmed again so it ranks higherid: string
storybloq_ruling_list
Lists recorded design decisionsscopeTag?: stringsuperseded?: boolean
storybloq_ruling_get
Reads one decisionid: string
storybloq_ruling_create changes
Records a design decisiontext: stringattribution: enumdate: stringscopeTags?: arraycites: arrayclientTaskId?: string
storybloq_ruling_supersede changes
Replaces an earlier decision with a new oneid: stringwith?: stringtext?: stringattribution?: enumdate?: stringscopeTags?: arrayclientTaskId?: string
storybloq_handover_list
Lists session handovers
storybloq_handover_latest
Reads the most recent handovercount?: integerbrief?: booleanpriming?: booleanformat?: enum
storybloq_handover_get
Reads one handoverfilename: stringformat?: enum
storybloq_handover_create changes
Writes a handover for the next sessioncontent: stringslug?: string
storybloq_blocker_list
Lists recorded blockers
storybloq_snapshot changes
Saves project state so later sessions can diff against it
storybloq_recap
Shows what changed since the last snapshot and suggests next steps
storybloq_recommend
Ranks tickets and issues worth doing nextcount?: integernode?: string
storybloq_export
Builds one self-contained document of the projectphase?: stringall?: boolean
storybloq_validate
Checks .story/ files for broken references and schema errorsformat?: enumintegrityOnly?: boolean
storybloq_selftest changes
Smoke test that creates, edits and deletes temporary records
storybloq_health
Reports whether the installed server and its setup answer as expectedformat?: enumonly?: arrayrefresh?: boolean
storybloq_autonomous_guide changes
Steps an autonomous session through pick, plan, review, test, implement and finalizesessionId: stringaction: enumclientTaskId?: stringtakeover?: booleanownerGoneCandidateTakeover?: objectownerGoneCandidateCancel?: objectmode?: enumreviewEffort?: enumticketId?: stringtargetWork?: arrayreport?: object
storybloq_review_lenses_prepare changes
Sets up a multi-lens review roundstage: enumdiff: stringchangedFiles: arrayticketDescription?: stringreviewRound?: integerpriorDeferrals?: arraysessionId?: stringtarget?: string
storybloq_review_lenses_judge
Judges the findings of the review lensesreviewVerdict: anyconvergenceHistory?: array
storybloq_review_lenses_synthesize changes
Merges lens findings into one review verdictstage?: enumlensResults?: arrayactiveLenses: arrayskippedLenses: arrayreviewRound?: integerreviewId?: stringdiff?: stringchangedFiles?: arraysessionId?: stringcitedRulingsUndelivered?: object
storybloq_session_report
Analyses an autonomous session, even when project state is damagedsessionId: string
storybloq_session_guard
Says whether another session is running and whether writing is allowedclientTaskId?: string
storybloq_session_intel
Reports context use and how close the session is to auto-compactionformat?: enumsessionId?: stringtranscript?: stringcallerModel?: stringfull?: booleanclientTaskId?: string
storybloq_session_milestone changes
Posts a self-reported progress stage onto this session's presence recordkind: enumgateName?: stringnote?: stringclientTaskId?: string
storybloq_register_subprocess changes
Registers a child process so the Mac app can show itpid: integercmd: stringcategory: enumsessionId: string
storybloq_roster_get
Lists live and stale sessions and subagents (read-only)format?: enumall?: boolean
storybloq_arrangement_create changes
Creates a duet or wave arrangement between sessionsbounds: arrayparties: arrayonIrreversibleWork: enumonReversibleWork?: enum
storybloq_arrangement_get
Reads an arrangementid: stringformat?: enum
storybloq_arrangement_update changes
Suspends, resumes or closes an arrangementid: stringlifecycle: enum

Similar servers