storybloq

Storybloq

Your project’s memory. Your agents’ workflow. Project memory and workflows for Claude Code and Codex. Keep stories, plans, handovers, and review evidence beside your code. Pick up work across sessions and follow progress in the optional Mac app.

storybloq.com · Mac app · Review lenses · Privacy

---

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 projec