Storybloq: a .story directory on disk, four surfaces, and a manifest ahead of its own tags
Cross-session context for Claude Code. CLI + MCP server + /story skill that tracks tickets, issues, handovers, and roadmap in a .story/ directory.
At a glance
- What is it?
- Project memory for Claude Code and Codex, kept as JSON and markdown in a .story folder you can commit. The interesting parts sit at the edges: a second binary the README never names, a context figure that is explicitly not a share of the model window, and a package version higher than any published tag.
- Who is it for?
- Storybloq is a coherent answer to a narrow problem, and the parts that would usually be marketing are unusually honest: the README states that its own approval records do not replace tests or CI, and that recovery depends on the client and the interruption. Before installing, read the LICENSE file rather than the metadata, expect to run on a version published from npm rather than the branch, and decide whether you want a second MCP server registered into your client by setup.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Storybloq/storybloq788 ★ · +55
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| Storybloq/storybloq | 733 | 788 |
55 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One directory, four surfaces, and a second binary
Everything lives in a .story directory inside your repository: stories, issues, roadmap phases, session handovers and lessons learned, as JSON and markdown files you can track with Git. Stories use ticket records in both the CLI and the file format.
Four surfaces read and write that directory. The CLI is invoked as storybloq. The MCP server exposes structured tools that Claude Code and Codex call directly. The skill is invoked as /story in Claude Code or $story in Codex to load project state at the start of a session. The Mac app is a native sidebar that watches .story and updates live while a client works, sold separately and free on the App Store.
The package manifest declares two binaries, not one: storybloq points at dist/cli.js and storybloq-presence points at dist/presence.js. Every command in the documentation is storybloq. The presence binary, which is the name the 12 hour freshness rule below belongs to, is never shown to a reader.
The dependency list also stops part way: @modelcontextprotocol/sdk, @storybloq/lenses, canonicalize and proper-lockfile appear, and the next entry begins with three letters before the text ends.
Install is two commands and a client version floor
npm install -g @storybloq/storybloq@latest
storybloq setup --client allThe requirements are stated in one sentence: Node.js 20 or newer, and at least one AI client, which is either Claude Code or Codex CLI 0.130.0 or newer. The manifest agrees on the engine floor, with node set to >=20 in the engines block.
Installation is global rather than project local, and the tag used is latest, so the version you get is whatever npm last published rather than whatever the default branch holds. Releases are also tagged in the repository, and the three most recent tags are close together: v1.15.7 at 00:59 UTC on 2026-09-20, v1.15.8 at 04:30, and v1.15.9 at 04:41 the same morning.
That cadence matters when reading the version numbers, because the manifest in the tree is already past all of them.
setup --client all registers a second MCP server you did not ask for
The setup command does three visible things: it installs the Storybloq skill for Claude and Codex, registers this package as an MCP server, and configures whatever client hooks are available.
It also does a fourth, conditional one. When Codex is installed, setup registers the bundled codex-claude-bridge review backend as a second MCP server named codex-bridge. The bridge is an optional dependency, so a copy you registered yourself is left alone, and storybloq health launches whichever one is registered and reports whether it answers.
The failure mode is documented plainly. The bridge needs a Codex CLI login to review anything, with agy named as the Gemini failover; without a login it registers successfully and reviews fail. Re-running setup is safe. On the Codex side, installed hooks are reported with a trust value of unknown, and you are told to open /hooks to review and trust them. The older setup-skill command survives as a compatibility alias for Claude-only setup.
So a single setup call can add a login-dependent review service to your editor. Nothing in the README asks whether you want it.
The footer context number is not a share of the model window
Setup also installs the ledger dashboard for Claude Code. On version 2.1.272 or newer, a project that has a .story directory draws its tickets, issues and progress in a pane beside the transcript, with no extra flag on the install command and nothing to configure. Projects without a .story directory show nothing at all. The dashboard is turned off with /plugin configure storybloq.
The number in the footer is the part worth reading carefully, because the README goes out of its way to say what it is not. It is how full the session is toward its automatic compaction point, not a share of the model's context window, and it reaches 100 percent when compaction is due rather than when the window is full. It refreshes during a turn as tools run, at most every five seconds.
That is an unusual thing to document. Most tools display a token gauge that users read as remaining capacity; here the same number means the opposite, and the documentation says so explicitly.
A stage tag read from status.json, with a 12 hour freshness rule
While a /story auto session runs, the dashboard shows an In progress card for whatever the session is working on: a ticket, or, while it fixes an issue, that issue. The card carries its stage after the id, in the form T-001 [Code] Native canvas, document objects, and local saving. When no card on screen belongs to the session, because nothing has been picked yet, the item is not in progress, or the column limit cut it off, the In progress heading carries the stage instead, as in In progress 1 [Code]. There is no footer line for the session.
The stage is read from .story/status.json and nothing else. When that file is older than 12 hours, which the README calls the presence TTL, the stage is drawn dimmed with a question mark, as in [Code?], because nothing has confirmed it since.
The truncation order is specified too, which is the sort of detail that normally goes unwritten. When the pane is narrow, the title is cut first, and the tag is dropped before the id is shortened or the heading's count is cut. A person reading the pane can therefore tell exactly which piece of information was sacrificed.
The project says its own records are not evidence
The documentation defines its vocabulary tightly and then disclaims the value of it. A lesson is a recorded pattern or mistake, with reinforcement so useful guidance surfaces again. An approval records acceptance of particular work within the workflow that requested it. Coordination records participants and assignments, and the client or configured transport supplies dispatch and messages. Recovery uses saved state and checks before continuing rather than assuming an interrupted action finished.
The disclaimer is in the workflow section and is worth quoting in substance. Gate acknowledgments in duet workflows can pin acceptance to a plan or a staged code state, and the records help you inspect the work, but they do not guarantee correct code and do not replace tests, CI and release checks. Persisted session state supports guarded continuation, and automatic recovery depends on the client and the interruption.
That is a project saying plainly that its approval trail is an audit convenience rather than a quality gate, which is the most useful sentence in the README for anyone deciding whether to adopt it.
The manifest is at 1.16.0 and the newest tag is v1.15.9
The package manifest declares version 1.16.0. The three most recent releases are v1.15.7, v1.15.8 and v1.15.9, all published on 2026-09-20 within about four hours of each other. The newest tag therefore sits below the version in the tree, and the install command, which pulls @latest from npm, gets the published line rather than the branch.
Nothing is wrong with that on its own, since a repository is normally ahead of its last release. It does mean that features described in the README may not be in the installed package, and that reading the tree tells you nothing about what a colleague gets from npm.
The licence situation has a similar shape and needs more care. The repository's licence metadata carries no verdict, while the manifest declares PolyForm-Shield-1.0.0, and the root carries both a LICENSE file and a NOTICE file. Three places, three levels of specificity. The manifest identifier and the LICENSE text are the ones to read before installing this into anything commercial, and the NOTICE file is shipped in the published tarball on purpose.
What the published tarball contains, and what it leaves out
The files array in the manifest is short and deliberate. It ships dist, which is the built output, then src/skill, then three plugin paths: the Claude plugin manifest, the hooks configuration, and the hook sources as plugins/storybloq/hooks/*.ts. It then excludes plugins/storybloq/hooks/*.test.ts with a negated pattern, and adds README.md and NOTICE.
So the package carries compiled output plus the skill definition and the hook sources, and it deliberately leaves the hook tests behind. The repository itself keeps more: AUTHORING.md, MANUAL_TEST_PLAN.md, TEAM_CI.md, SESSION_PRIMING_COMPARISON.md, SECURITY.md, an assets directory, a bench directory, scripts, src and a test directory, alongside tsup for building and vitest for testing.
That split explains where the dashboard comes from. The ledger pane described for Claude Code 2.1.272 and newer is implemented in the hook sources the package does ship, which is why it needs no flag at install time, and why the plugin manifest and hooks configuration are published alongside the binary rather than fetched at runtime.
Editorial conclusion
Storybloq is a coherent answer to a narrow problem, and the parts that would usually be marketing are unusually honest: the README states that its own approval records do not replace tests or CI, and that recovery depends on the client and the interruption. Before installing, read the LICENSE file rather than the metadata, expect to run on a version published from npm rather than the branch, and decide whether you want a second MCP server registered into your client by setup.
Frequently asked questions
What is Storybloq and what goes into the .story directory?
Storybloq is a CLI, an MCP server and a skill for Claude Code and Codex that keep project memory in a .story directory inside your repository. Stories, issues, roadmap phases, session handovers and lessons learned live there as JSON and markdown files you can track with Git.
What does storybloq setup --client all change on my machine?
It installs the Storybloq skill for Claude and Codex, registers the package as an MCP server, and configures available client hooks. When Codex is installed it also registers the bundled codex-claude-bridge package as a second MCP server named codex-bridge, which needs a Codex CLI login before it can review anything, with agy as the Gemini failover.
What does Storybloq require to install?
Node.js 20 or newer, and at least one AI client: Claude Code or Codex CLI 0.130.0 or newer. The two commands are npm install -g @storybloq/storybloq@latest followed by storybloq setup --client all.
Which licence does Storybloq ship under?
The package manifest declares PolyForm-Shield-1.0.0, and the repository root carries both a LICENSE file and a NOTICE file, while the repository's licence metadata carries no verdict. The manifest identifier and the LICENSE text are what to read, not the metadata.
What does the stage tag in the Storybloq dashboard mean?
It is a stage tag carried after the ticket id, in the form T-001 [Code] ..., read from .story/status.json alone. If that status file is older than the 12 hour presence TTL, the stage is drawn dimmed with a question mark, because nothing has confirmed it since.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/storybloq-storybloq)Star history chart for your README
[](https://hysenlabs.com/projects/storybloq-storybloq)Was this useful?