storybloq

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: structured tools Claude Code and Codex can call directly, with five additional tools when the local Bus is enabled. 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. 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.

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 or Codex:

• /story in Claude Code or $story in Codex - 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 / $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 / $story review T-001 - runs the multi-lens review (see Storybloq/lenses) against a ticket's diff.
• /story orchestrate / $story orchestrate - drives a multi-repo (or large single-repo) backlog when the client exposes exact callable workflow/subagent tools. Codex uses multi_agent_v1.spawn_agent, its normalized multi_agent_v1__spawn_agent identifier, or an exact spawn_agent tool. The Claude Agent View-backed storybloq dispatch command is shipped; a product-managed Codex dispatch backend is not.
• /story bus / $story bus - polls a task-bound local Bus endpoint so an implementer and an independent reviewer can exchange advisory findings without copy and paste.
• /story handover / $story handover - writes a session handover capturing decisions, blockers, and next steps.

Both clients support context loading, autonomous mode, MCP, and compaction/status hooks. Codex Desktop can open an autonomous session's owning task and relay an exact owner response to it; Codex CLI safely falls back to a manual task switch. Autonomous code review defaults to a 12-round landing cap (clamped upward by ticket risk): unresolved critical findings and rejects still block, while non-blocking findings become follow-up issues at the cap. Set recipeOverrides.stages.CODE_REVIEW.maxReviewRounds to 0 to disable the cap explicitly.

recipeOverrides.compactThreshold accepts medium, high (default), or critical. The value selects both the pressure limits and the rotation trigger: medium uses lower limits and rotates at medium pressure, while critical uses higher limits and waits for critical pressure. At a clean COMPLETE boundary, threshold pressure ends the bounded session through HANDOVER because Storybloq cannot invoke a client compaction command. When the client itself compacts, the PreCompact and SessionStart hooks preserve the same session; pressure resets only after SessionStart confirms source: compact.

Outside the AI client, the same state is one storybloq invocation away.

Storybloq Bus

Storybloq Bus is an optional local coordination protocol for one implementer task and one reviewer task. Runtime state lives under gitignored .story/bus/; confirmed findings still become canonical Storybloq issues with durable source provenance before they are sent as issue notices.

storybloq bus init
storybloq bus join implementer --client codex
storybloq bus join reviewer --client claude
storybloq bus hooks enable --client codex
storybloq bus hooks enable --client claude

Bus runtime is local and gitignored, so run storybloq bus init once in each checkout that will participate. Status and doctor report a fresh checkout as enabled but not initialized; that healthy inactive state does not block commits or autonomous FINALIZE. Other Bus commands and MCP tools never initialize the runtime implicitly. Initialization rejects symlinked ignore files and negation patterns because it cannot safely prove that Git will exclude the complete runtime otherwise.

The foreground protocol includes send, poll, acknowledge, thread state, status, doctor, export, and ship checks. Messages are hash-chained, idempotent, bounded, task-bound, secret-screened, and delivered through crash-recoverable recipient mailboxes. Critical messages require a matching unresolved critical issue by default. Bus text is always peer-agent advice: it never grants owner approval or authorizes merge, push, signing, deployment, credentials, spending, or destructive actions.

V1 does not include a daemon, process spawning, headless resume, or automatic offline wake. Natural SessionStart/Stop hooks and explicit polling are the delivery paths. Codex Desktop remains non-wakeable.

Federation

Federation coordinates AI agent work across multiple repos. O