Storybloq: a .story/ directory as shared memory for Claude Code and Codex
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?
- Storybloq turns cross-session context into a git-tracked file convention, exposed through a CLI, an MCP server and a /story skill. The design is legible and inspectable, but the licence is PolyForm Shield and the Codex plugin path is explicitly untested.
- Who is it for?
- Adopt Storybloq if you already run Claude Code or Codex across multi-day work and want project state to live in git rather than in a CLAUDE.md you keep rewriting. Skip it if you work in short single-session bursts, if you need an OSI-approved licence, or if you are on Codex with an existing standalone skill copy, since the README calls the plugin-plus-standalone combination untested.
- 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 received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The statelessness problem Storybloq is aimed at
The README states the premise directly: AI coding assistants are stateless, so every session starts from zero and the model does not know what was built yesterday, what is broken, or which decisions were already settled. The project's own framing of the cost is worth quoting because it defines the scope of the tool. It says the real cost is not wasted setup time but repeated mistakes, relitigated design decisions, hallucinated context, and work that stays linear instead of compounding. That is a narrower claim than general project management. Storybloq is for a developer who runs Claude Code or Codex across several days on the same repository and keeps re-explaining the same state. It is not aimed at a team that needs a shared issue tracker with permissions, notifications and reporting. The unit of value here is one developer plus one agent plus one repository, with git as the transport.
A file convention first, tooling second
The core mechanism is a directory, not a service. Every project gets a .story/ folder of JSON and markdown files holding tickets, issues, roadmap phases, session handovers and lessons learned. The README notes these are tracked by git and readable by any AI. That ordering matters: the durable artifact is plain files, and the CLI, MCP server, skill and Mac app are all readers and writers over the same directory. storybloq init --name "your-project" scaffolds config.json for project config and recipe overrides, roadmap.json for phase ordering and metadata, and tickets/, issues/ and notes/ directories with numbered entries such as T-001.json and ISS-001.json. Because the store is files under version control, a handover written at the end of one session is diffable, reviewable and recoverable. The trade-off is equally plain: there is no server-side index, so anything that needs cross-repository querying has to be built on top. The Federation feature, referenced in the README and named in the v1.13.0 release as federation parity, is the project's answer to multi-repo projects, but the supplied material does not describe its mechanics.
Four surfaces over the same directory
Storybloq ships four ways to reach .story/. The CLI, invoked as storybloq, inspects and mutates the directory from a terminal. The MCP server exposes structured tools that Claude Code and Codex call directly, and the README is specific that this involves no subprocess spawning, with five additional tools available when the local Bus is enabled. A skill provides /story in Claude Code and $story in Codex to load project state at session start. The Mac app is a separate product that watches .story/ and updates live while the AI client works. The MCP detail is the one worth pausing on. Spawning a CLI per tool call is the common shortcut in this category, and it costs process startup on every invocation and makes the tool boundary fuzzy. Registering a server means the agent sees typed tools instead. The README does not document what the five Bus tools do, so treat that as an open question to check after install rather than a known capability.
Install, setup and the upgrade path
Installation is two commands. npm install -g @storybloq/storybloq@latest, then storybloq setup --client all. The README states the requirements as Node.js 20 or newer and at least one AI client, Claude Code or Codex CLI 0.130.0 or later. setup --client all installs the Storybloq skill for both Claude and Codex, registers the package as an MCP server, and configures available client hooks. Re-running it is described as safe, and setup-skill remains as a compatibility alias for Claude-only setup. Two operational details are worth knowing before you run it. Codex reports installed hooks with trust unknown, and the README tells you to open /hooks in Codex to review and trust them, which means the hook configuration is not silently trusted on your behalf. Separately, the CLI refreshes the skill directory and migrates legacy hook entries on the first run after an upgrade, including entries from the pre-rename @anthropologies/claudestory package. Upgrading is the same two commands as a fresh install, and the CLI prints a one-line banner when a newer version is on npm.
The Codex marketplace path and its untested edge
There is a second install route for Codex: codex plugin marketplace add https://github.com/Storybloq/storybloq followed by codex plugin add storybloq@storybloq. The README is unusually candid about its limits. This installs the skill only. It does not run the npm install, register the MCP server, or configure hooks. Those are handled by the skill's own bootstrap step on your first $story, which runs npm install -g @storybloq/storybloq@latest and then storybloq setup --client codex --skip-skill. The --skip-skill flag exists because the plugin already manages the skill copy. The genuinely useful warning is about overlap. If you already have a standalone Codex skill copy from a prior storybloq setup --client codex, at ~/.agents/skills/story/ or ~/.codex/skills/story/, installing the marketplace plugin on top is described as an untested configuration, not a verified-harmless one, because Codex's handling of two same-named skill providers has not been tested by the project. The README also flags a trap in the migration: a backup left under ~/.agents/skills/ still contains a SKILL.md and can be discovered as a second skill, which is the duplicate you were trying to remove. The suggested move parks it one level up, into ~/.agents/story-skill-backups/, with the same treatment for ~/.codex/skills/story.
Where the file convention stops being enough
The main limitation follows from the architecture. .story/ is per-repository state in git, which is excellent for one developer and one agent and awkward for anything else. Two developers working the same tickets will meet merge conflicts in JSON files, and the README does not describe a conflict-resolution story. There is no mention of access control, so anything written into .story/ is as visible as the repository itself, which rules it out for projects where ticket text carries security or customer detail. The statelessness problem is also not universal. If your sessions are short and self-contained, or if a single CLAUDE.md already covers your project, the four surfaces and the setup step are overhead you will not recover. And the licence is a real constraint rather than a footnote: the badge in the README reads PolyForm Shield 1.0, while the repository metadata reports NOASSERTION. PolyForm Shield is a source-available licence, not an OSI-approved open source licence, so anyone whose policy requires OSI approval should read the LICENSE file before adopting. This is a factual note about the licence identifier, not legal advice.
The alternative is the CLAUDE.md you already have
The honest comparison is not another context tool. It is the pattern the README names as the thing developers compensate with: a CLAUDE.md file plus scattered notes. That approach costs nothing to start and needs no install. The difference in approach is structural. A CLAUDE.md is prose that a human maintains and an agent reads in full, so it grows monotonically and eventually competes with your actual task for context. Storybloq splits the same information into typed records with stable identifiers, T-001 and ISS-001, and lets the agent fetch the subset it needs through MCP tools rather than reading everything. That is the argument for the extra machinery. It also explains the cost: you now maintain a directory schema, and the schema is a dependency you upgrade. If your notes fit comfortably in one file you read at the start of each session, the typed store buys you little.
Maintenance cost and who should wait
The release cadence visible in the supplied material is fast. v1.12.0 introduced duet mode, v1.13.0 was labelled federation parity, and v1.14.0 landed on the same day as the most recent push, all within roughly ten days at the end of August and the start of September 2026. Frequent releases are not a quality signal by themselves, but they do mean the setup command is the part you will re-run most. The good news is that the upgrade procedure is the install procedure, and the CLI sweeps stale hook entries and migrates legacy ones automatically, including from the old @anthropologies/claudestory package name. The bad news is that a tool that rewrites your AI client's hook configuration on upgrade is a tool whose release notes you should read before running setup. The README itself treats the Codex plugin plus standalone skill combination as untested, and that is the configuration to avoid until you can verify it yourself. Start with one repository, run storybloq init, and confirm that the generated .story/config.json and roadmap.json match how you actually work before you point a multi-day project at it.
Editorial conclusion
Adopt Storybloq if you already run Claude Code or Codex across multi-day work and want project state to live in git rather than in a CLAUDE.md you keep rewriting. Skip it if you work in short single-session bursts, if you need an OSI-approved licence, or if you are on Codex with an existing standalone skill copy, since the README calls the plugin-plus-standalone combination untested. Before committing, run storybloq init in one throwaway repo, inspect the generated .story/config.json and roadmap.json, and confirm that storybloq setup --client all writes the hook entries you expect rather than ones you have to remove.
Community notes