Storybloq: cross-session memory for Claude Code and Codex

What Storybloq fixes, and for whom

The README states the problem plainly: AI coding assistants are stateless, and every new session starts from zero. The model does not know what was built yesterday, what is broken, what decisions were made, or what to work on next. Developers patch this with CLAUDE.md files and scattered notes, but the README argues there is no standard structure, no session continuity and no tooling. The cost it names is not setup time. It is repeated mistakes, relitigated design decisions, hallucinated context and work that stays linear instead of compounding.

That framing sets the audience. Storybloq is for a developer who runs Claude Code or Codex against a repository over days or weeks and wants the assistant to pick up the ticket it was on, the open issue it left behind, and the handover note from the last session. It assumes the repository is the unit of work and that git is the transport. A solo developer with a long-running repo is the core case. A team works too, because .story/ is tracked by git, but the tool is shaped around an AI client reading project state at the start of a session, not around humans planning sprints in a browser.

The .story/ directory is the whole data model

Storybloq is a file convention before it is a program. Running `storybloq init` scaffolds a .story/ directory inside the project. According to the README that directory holds config.json for project config and recipe overrides, roadmap.json for phase ordering and metadata, and then tickets/, issues/ and notes/ directories with files named T-001.json, ISS-001.json and N-001 respectively. Everything is JSON and markdown, tracked by git, and readable by any AI client that can read files.

Four surfaces sit on top of that directory. The `storybloq` CLI inspects and mutates .story/ from the terminal. An MCP server exposes structured tools that Claude Code and Codex call directly, with five additional tools when the local Bus is enabled, and the README notes it does not spawn subprocesses. A skill, invoked as `/story` in Claude Code or `$story` in Codex, loads project state at the start of every session. A separate Mac app watches .story/ and updates a native sidebar live while the AI client works; the README calls it a separate product, free on the App Store.

The design choice worth noting is that the source of truth stays in the repository. Nothing is hidden in a service, so a teammate who never installs Storybloq can still read the tickets as files, and a diff review shows what changed. The trade-off is that .story/ becomes part of your repository's history and your merge conflicts.

Install and first run

The README gives a two-command install. It requires Node.js 20+ and at least one AI client, Claude Code or Codex CLI 0.130.0 or later. The package is published on npm as @storybloq/storybloq.

npm install -g @storybloq/storybloq@latest
storybloq setup --client all

`setup --client all` installs the Storybloq skill for Claude and Codex, registers the package as an MCP server, and configures available client hooks. The README states that re-running it is safe. One detail to expect: Codex reports installed hooks with trust `unknown`, and you open `/hooks` in Codex to review and trust them. `setup-skill` still exists as a compatibility alias for Claude-only setup.

With the CLI installed, bootstrap a project from its root.

cd your-project
storybloq init --name "your-project"

That creates the .story/ directory described above. From then on, a session in Claude Code starts with the skill.

/story

In Codex the equivalent is `$story`. The README says the skill loads project state at the start of the session, which is the behaviour you are checking for: the assistant should be able to name the current ticket and the last handover without you pasting them in. If it cannot, the skill or the MCP registration did not land, and the fix is to re-run `storybloq setup --client all`.

Codex plugin install and the duplicate-skill trap

Codex users have a second path that skips the global npm install at first.

codex plugin marketplace add https://github.com/Storybloq/storybloq
codex plugin add storybloq@storybloq

This installs the skill only. The README is explicit that it does not run the npm install, register the MCP server, or configure hooks. Those arrive through the skill's own bootstrap step the first time you invoke `$story`: if the CLI or MCP server is not set up, the skill runs `npm install -g @storybloq/storybloq@latest` followed by `storybloq setup --client codex --skip-skill`. The `--skip-skill` flag skips re-copying skill files because the plugin already manages that copy.

The trap is an existing standalone skill copy from a prior `storybloq setup --client codex`, which lives at `~/.agents/skills/story/` or `~/.codex/skills/story/`. The README calls installing the marketplace plugin on top of it an untested configuration, not a verified-harmless one, because Codex's handling of two same-named skill providers has not been tested here. The recommended migration moves the old copy out of the skills root rather than deleting it.

mkdir -p ~/.agents/story-skill-backups && mv ~/.agents/skills/story ~/.agents/story-skill-backups/story.$(date +%s)

Parking the backup one level up matters. A copy left under `~/.agents/skills/` still contains a SKILL.md and can be discovered as a second skill, which is the duplicate the procedure exists to remove. Restart Codex and confirm `$story` still works through the plugin-managed copy. Rolling back means moving the backup to its original path. This is the most operationally fiddly part of the project, and it is the part most likely to bite someone who installed an early version.

Federation, upgrades and what the CLI does quietly

Multi-repo projects are handled through a feature the README calls Federation, referenced from the bootstrap section. The repository layout also shows a SESSION_PRIMING_COMPARISON.md file at the top level, which suggests the project documents how different priming approaches compare, though the README does not summarise its contents. Federation parity appears as the headline of the v1.13.0 release, and duet mode in v1.12.0, so both are recent additions rather than long-settled surfaces.

Upgrading is the same two commands as a fresh install. `npm install -g @storybloq/storybloq@latest` pulls the newest version, and `storybloq setup --client all` refreshes the skill files, re-registers the MCP server and sweeps stale hook entries from prior installs. The README says you will usually see a one-line banner on the next `storybloq` invocation when a newer version is on npm.

The part worth knowing about is what happens without being asked. On the first run after an upgrade, the CLI silently refreshes the skill directory and migrates legacy hook entries, including ones from the pre-rename `@anthropologies/claudestory` package. Silent migration is convenient and it also means the tool rewrites files under your home directory on a schedule you do not control. If you keep your skill files under configuration management, that is a collision you should plan for.

Where Storybloq is the wrong tool

The licence is the first constraint. The package.json declares PolyForm-Shield-1.0.0, and the README badge says the same. That is a source-available licence, not an OSI open source licence, and the repository's licence field is reported as NOASSERTION. If your organisation's policy is open-source-only, or if you intend to offer a competing product, read the licence text before you build a workflow on this. This is a description of the licence identifier, not legal advice.

The second constraint is the client requirement. Storybloq assumes Claude Code or Codex CLI 0.130.0 or later, and Node.js 20+. There is no documented path for a different assistant or for a plain terminal workflow that does not involve an AI client. If your team standardises on another editor's agent, the MCP server may or may not be reachable from it, and the README does not say.

The third is scope. Storybloq tracks tickets, issues, roadmap phases, handovers and lessons inside one repository's .story/ directory. It is not a replacement for an issue tracker that humans outside the repo read. There is no mention of notifications, assignments, permissions or a web view outside the Mac app. A team that wants a shared board will keep their existing tracker and use Storybloq as the AI-facing layer, which means two places to update unless someone automates the sync. The README does not document such a sync.

How it differs from a CLAUDE.md file

The obvious alternative is the file most Claude Code users already have: a CLAUDE.md at the repository root, plus notes kept wherever the developer puts them. The difference is structure and mutability. CLAUDE.md is prose the developer edits by hand; it tends to accumulate standing instructions and goes stale because updating it is a manual chore. Storybloq puts the same information into typed JSON records with identifiers, T-001 and ISS-001, and gives the AI client tools to read and write them through the MCP server, so a session can close a ticket or file an issue as part of its work rather than leaving a note for a human to transcribe.

That is the real distinction: CLAUDE.md is a briefing, and Storybloq is a record. A briefing is cheaper to start with and needs no install, no Node version, no MCP registration and no licence review. A record pays off when the number of sessions grows and the question changes from what is this project to what was I doing. If you have never lost an afternoon re-explaining an architectural decision to a fresh session, the CLAUDE.md path is the correct one.

Editorial conclusion

Adopt Storybloq if you already drive Claude Code or Codex on a repository and keep re-explaining the same decisions to a stateless assistant. Skip it if your work is one-shot prompts, if you cannot commit a .story/ directory to the repo, or if you want a tracker your whole team reads without an AI client. Before committing, verify three things: that Node.js 20+ is available, that ~/.agents/skills/ and ~/.codex/skills/ hold no standalone story skill copy that would collide with the plugin, and that the PolyForm Shield licence terms fit how you distribute your code.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. Storybloq/storybloq on GitHub