storybloq

The problem

A new coding session may be missing the decisions and unfinished work from the last. Project instructions describe how to work; handovers, stories, and review records capture what happened and where to continue.

The real cost isn't wasted setup time. It's repeated mistakes, relitigated design decisions, hallucinated context, and linear instead of compounding work.

The idea

Every project gets a .story/ directory of JSON and markdown files. Stories, issues, roadmap phases, session handovers, and lessons learned live there as readable files you can track with Git. Stories use ticket records in the CLI and file format.

• CLI: storybloq - inspect and mutate .story/ from the terminal.
• MCP server: structured tools Claude Code and Codex can call directly to read and update the project and guide supported workflows.
• Skill: invoke /story in Claude Code or $story in Codex to load project state at the start of a session.
• Mac app: native sidebar that watches .story/ and updates live while your AI client works (separate product, free on the App Store).

From choosing work to the next session

• Choose the next useful story. Recommendations account for blockers, unfinished work, and what completing a story would unblock. Recorded decisions and a ranked digest of lessons give the agent context for the choice.
• Build against a reviewed plan. Autonomous mode guides planning, configured independent reviews, tests, and finalization. Approved plan snapshots preserve the approach that advanced to implementation. Confirmed review findings can become durable issues.
• See what was approved. Know what was checked. Gate acknowledgments in duet workflows can pin acceptance to a plan or staged code state. These records help you inspect the work; they do not guarantee correct code or replace tests, CI, and release checks.
• Continue with the record intact. Handovers preserve decisions and next steps. Persisted session state supports guarded continuation; automatic recovery depends on the client and the interruption.

A lesson is a recorded pattern or mistake, with reinforcement to help useful guidance surface again. An approval records acceptance of particular work, within the workflow that requested it. Coordination records participants and assignments; the client or configured transport supplies dispatch and messages. Recovery uses saved state and checks before continuing, rather than assuming an interrupted action finished.

Start with one story and a handover. Add autonomous mode, coordination workflows, or federation when the project needs them.

Install

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

Requires Node.js 20+ and at least one AI client: Claude Code or Codex CLI 0.130.0+. Package lives on npm at @storybloq/storybloq; releases are tagged on this repo at github.com/Storybloq/storybloq/releases.

setup --client all installs the Storybloq skill for Claude and Codex, registers this package as an MCP server, and configures available client hooks. It also registers the bundled codex-claude-bridge review backend as the codex-bridge MCP server when Codex is installed; the bridge ships as an optional dependency of this package, so a copy you registered yourself is left alone and storybloq health launches whichever one is registered and reports whether it answers. The bridge needs a Codex CLI login to review (or agy for its Gemini failover); without one it registers but reviews fail. Re-running it is safe. Codex reports installed hooks with trust unknown; open /hooks in Codex to review and trust them. setup-skill remains as a compatibility alias for Claude-only setup.

Setup also installs the ledger dashboard for Claude Code. On version 2.1.272 or newer, a project with a .story/ directory draws its tickets, issues, and progress in a pane beside the transcript, with no extra flags on the install command and nothing to configure. Projects without .story/ show nothing. Turn the dashboard off with /plugin configure storybloq. The context figure in the footer is how full the session is toward its automatic compaction point, not a share of the model's window, so it reaches 100% when compaction is due; it refreshes during a turn as tools run, at most every five seconds.

While a /story auto session runs, the dashboard shows where it is. The In progress card the session is working, a ticket or, while it fixes an issue, that issue, carries its stage after the id, as in T-001 [Code] Native canvas, document objects, and local saving. When no card on screen is the session's own (nothing picked yet, the item not in progress, or cut off by the column's limit), the In progress heading carries the stage instead, as in In progress 1 [Code]. There is no footer line for the session. The stage comes from .story/status.json alone. A status older than 12 hours, the presence TTL, is drawn dimmed with a question mark ([Code?]) because nothing has confirmed it since. 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.

Your first two sessions

1. Open your project in Claude Code or Codex. Type /story in Claude Code chat or $story in Codex chat. For a new project, the skill guides you through setup.
2. Ask: “Record a story to add an empty calendar state. Record the decision that the API owns availability.”
3. Before stopping, ask: “Write a handover.”
4. Start a new chat and invoke /story or $story again to load the recorded project context.

See the work

The optional Mac app shows stories, progress, and handovers from your project files. Explore the Mac app or follow the tutorials.

Add structure as your work grows

Start with one project and one agent. Add autonomous workflows, independent review, or connected repositories when the work calls for them. Review records preserve what was checked; they do not guarantee correctness. Tests, CI, and release checks still matter.

The CLI and MCP server are source-available under PolyForm Shield. Your coding client and optional review backends have their own data handling and costs. See the privacy policy and the license below.

Upgrading

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

Same two commands as a fresh install: @latest pulls the newest version, and re-running setup refreshes the Storybloq skill files, re-registers the MCP server, and sweeps any stale hook entries from prior installs.

You'll usually see a one-line banner on the next storybloq invocation whenever a newer version is on npm:

storybloq v1.2.0 is available (you have v1.1.6).
Update: npm install -g @storybloq/storybloq@latest

The CLI also silently refreshes the skill dir and migrates any legacy hook entries (for example, from the pre-rename @anthropologies/claudestory package) on the first run after an upgrade — no manual cleanup needed.

Alternative install via the Claude Code plugin system: see Storybloq/plugin-archive (legacy path; storybloq setup --client all is the recommended install).

Codex plugin marketplace

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

This installs the Storybloq skill only. It does not run this package's npm install, register the MCP server, or configure hooks -- those still need the CLI, which the skill's own bootstrap step installs for you the first time you invoke it: on your first $story, if the CLI or MCP server isn't set up yet, the skill runs npm install -g @storybloq/storybloq@latest followed by storybloq setup --client codex --skip-skill for you. --skip-skill skips re-copying the skill files, since the plugin already manages that copy -- passing it yourself only matters if you're driving storybloq setup directly instead of letting the skill's bootstrap step do it.

If you already have a standalone Codex skill copy from a prior direct storybloq setup --client codex (at ~/.agents/skills/story/ and/or `~/.codex/skills/story/