storybloq

Cross-session context persistence for AI coding.

A file convention, a CLI, an MCP server, and a Claude Code skill that together turn every coding session into a building block instead of a reset.

storybloq.com · Mac app · Review lenses · Privacy

The problem

AI coding assistants are stateless. Every new session starts from zero. The model doesn't know what was built yesterday, what's broken, what decisions were made, or what to work on next. Developers compensate with CLAUDE.md files and scattered notes, but there's no standard structure, no session continuity, and no tooling.

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. Tickets, issues, roadmap phases, session handovers, and lessons learned all live there, tracked by git, readable by any AI.

• CLI: storybloq - inspect and mutate .story/ from the terminal.
• MCP server: 53 tools Claude Code and Codex can call directly, no subprocess spawning.
• Skill: /story in Claude Code or $story in Codex loads project state at the start of every session.
• Mac app: native sidebar that watches .story/ and updates live while your AI client works (separate product, free on the App Store).

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. Re-running it is safe. setup-skill remains as a compatibility alias for Claude-only setup.

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).

Bootstrap a project

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

For multi-repo projects, see Federation below.

That scaffolds:

.story/
├── config.json         project config + recipe overrides
├── roadmap.json        phase ordering + metadata
├── tickets/            T-001.json, T-002.json, ...
├── issues/             ISS-001.json, ISS-002.json, ...
├── notes/              N-001.json, N-002.json, ...
├── lessons/            L-001.json, ...
├── handovers/          YYYY-MM-DD-<slug>.md
└── snapshots/          state snapshots (gitignored)

Commit everything except .story/snapshots/.

Daily use

Inside Claude Code:

• /story - loads project status, reads the latest handover, surfaces open tickets and issues, lists blocked work, summarizes recent changes. When the client can run background agents and the actionable backlog is large, it also surfaces the orchestrate working style proactively (a recommendation, still gated by explicit opt-in).
• /story auto T-001 T-002 ISS-013 - autonomous mode scoped to those items. Drives a ticket through plan -> plan review -> implement -> tests -> code review -> commit with handovers at each checkpoint.
• /story review T-001 - runs the multi-lens review (see Storybloq/lenses) against a ticket's diff.
• /story orchestrate - drives a multi-repo (or large single-repo) backlog as an orchestrator: scouts verify state, enrichment agents rewrite items into byte-verified specs, a cheaper tier implements when the client offers one, and the session model reviews and gates every ship.
• /story handover - writes a session handover capturing decisions, blockers, and next steps.

Outside Claude Code, the same state is one storybloq invocation away.

Federation

Federation coordinates AI agent work across multiple repos. One project becomes the orchestrator. It declares which repos (nodes) are part of the system, how they depend on each other, and how they communicate at runtime. Each node keeps its own .story/ with its own tickets, issues, and handovers. The orchestrator reads across all of them.

# Create an orchestrator
storybloq init --type orchestrator --name "my-platform"

# Register nodes
storybloq node add api --path ../api --stack typescript --role "REST backend"
storybloq node add web --path ../web --stack nextjs --depends-on api
storybloq node add sdk --path ../sdk --stack typescript

Three relationship types connect nodes:

• dependsOn on node config: build-order edges. The web app depends on the API.
• links on node config: runtime integration. The web app calls the API over HTTP.
• crossNodeBlockedBy on tickets: a ticket in one repo is blocked until a ticket in another repo is complete. Example: "crossNodeBlockedBy": ["api:T-012"].

From the orchestrator directory:

storybloq status              # aggregated view across all nodes
storybloq recommend           # federation-aware suggestions (bottlenecks, stale nodes, blockers)
storybloq ticket list --node api   # list tickets in the api node without cd-ing

The recommendation engine generates federation-specific suggestions: nodes blocking downstream work, bottleneck nodes depended on by many others, nodes with no handover in two weeks. Tickets with crossNodeBlockedBy refs never surface in recommendations until the blocking ticket is complete.

CLI reference

All commands accept --format json|md (default md). Pipe JSON through jq for scripting, read the markdown variant directly.

Project

Phases

Tickets

Issues

Notes and lessons

Handovers, blockers, snapshots

Federation (orchestrator projects)

Team (team-mode projects)

See Team mode for the merge model these commands operate on.

MCP server reference

Register with Claude Code or Codex (done automatically by setup):

claude mcp add storybloq -s user -- storybloq --mcp
codex mcp add storybloq --env STORYBLOQ_CLIENT=codex -- storybloq --mcp

The server imports the same TypeScript modules as the CLI directly, so there's no subprocess overhead. It auto-discovers the project root by walki