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.

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/), installing the marketplace plugin on top of it is an untested configuration, not a verified-harmless one -- Codex's handling of two same-named skill providers isn't something this project has tested. Recommended migration: move the existing copy OUT of the skills root rather than deleting it. A backup left under ~/.agents/skills/ (for example story.bak) still contains a SKILL.md and can be discovered as a second skill, which is the duplicate this procedure exists to remove, so park it one level up instead: mkdir -p ~/.agents/story-skill-backups && mv ~/.agents/skills/story ~/.agents/story-skill-backups/story.$(date +%s), and the same for ~/.codex/skills/story into ~/.codex/story-skill-backups/ if present. Restart Codex and confirm $story still works via the plugin-managed copy. To roll back, move the backup to its original path. Only then, separately and at your own discretion, remove the backup.

If the CLI or MCP server is still missing after installing the plugin and invoking $story once, run the bootstrap command yourself: `npm install -g