GitPedia

Storybloq

Cross-session context for Claude Code. CLI + MCP server + /story skill that tracks tickets, issues, handovers, and roadmap in a .story/ directory.

From Storybloq·Updated June 29, 2026·View on GitHub·

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. The project is written primarily in TypeScript, distributed under the Other license, first published in 2026. Key topics include: agentic-development, ai-development, anthropic, claude-code, claude-skill.

Latest release: v1.4.4— v1.4.4 - Windows path fix
May 30, 2026View Changelog →
<p align="center"> <img src="https://raw.githubusercontent.com/Storybloq/storybloq/main/assets/logo.png" width="120" alt="Storybloq logo" /> </p> <h1 align="center">storybloq</h1> <p align="center"> <strong>Cross-session context persistence for AI coding.</strong><br /> 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. </p> <p align="center"> <a href="https://www.npmjs.com/package/@storybloq/storybloq"><img src="https://img.shields.io/npm/v/@storybloq/storybloq?color=333&label=npm" alt="npm version" /></a> <a href="https://github.com/Storybloq/storybloq/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-PolyForm--NC%201.0-blue" alt="License" /></a> <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen" alt="Node" /> <img src="https://img.shields.io/badge/claude%20code-compatible-orange" alt="Claude Code compatible" /> </p> <p align="center"> <a href="https://storybloq.com">storybloq.com</a> · <a href="https://storybloq.com/mac">Mac app</a> · <a href="https://github.com/Storybloq/lenses">Review lenses</a> · <a href="https://storybloq.com/privacy">Privacy</a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/Storybloq/storybloq/main/assets/hero.png" alt="Storybloq Mac app showing a live project sidebar alongside a Claude Code terminal" /> </p>

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

bash
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

bash
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

bash
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/.

<p align="center"> <img src="https://raw.githubusercontent.com/Storybloq/storybloq/main/assets/board.png" alt="Ticket board showing phases, tickets, and in-progress work" /> </p>

Daily use

Inside Claude Code:

  • /story - loads project status, reads the latest handover, surfaces open tickets and issues, lists blocked work, summarizes recent changes.
  • /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 handover - writes a session handover capturing decisions, blockers, and next steps.

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

<p align="center"> <img src="https://raw.githubusercontent.com/Storybloq/storybloq/main/assets/autonomous.png" alt="Autonomous mode running a ticket through plan, implement, test, review" /> </p>

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.

bash
# 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:

bash
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

CommandDescription
storybloq init [--name] [--type orchestrator] [--force]Scaffold .story/ (add --type orchestrator for multi-repo)
storybloq statusProject summary with phase statuses, counts, and risks
storybloq validateReference integrity + schema checks
storybloq setup --client claude|codex|all [--skip-hooks]Install Storybloq skills, register MCP, and configure client hooks
storybloq setup-skill [--skip-hooks]Compatibility alias for storybloq setup --client claude
storybloq recommend --count NContext-aware work suggestions

Phases

CommandDescription
storybloq phase listAll phases with derived status (status is computed from tickets, never stored)
storybloq phase currentFirst non-complete phase
storybloq phase tickets --phase <id>Leaf tickets for a phase
storybloq phase create --id --name --label --description [--summary] --after/--at-startCreate a phase
storybloq phase rename <id> [--name] [--label] [--description] [--summary]Update phase metadata
storybloq phase move <id> --after/--at-startReorder
storybloq phase delete <id> [--reassign <target>]Delete (reassign contained tickets)

Tickets

CommandDescription
storybloq ticket list [--status] [--phase] [--type]List leaf tickets (umbrellas excluded)
storybloq ticket get <id>Full ticket detail
storybloq ticket nextHighest-priority unblocked ticket
storybloq ticket blockedAll currently blocked tickets
storybloq ticket create --title --type --phase [--description] [--blocked-by] [--parent-ticket] [--node <name>]Create (use --node from orchestrator)
storybloq ticket update <id> [--status] [--title] [--phase] [--cross-node-blocked-by] [--node <name>] ...Update
storybloq ticket meta get|set|unset <id> [path] [value]Manage custom passthrough metadata
storybloq ticket delete <id> [--force]Delete

Issues

CommandDescription
storybloq issue list [--status] [--severity]List issues
storybloq issue get <id>Issue detail
storybloq issue create --title --severity --impact [--components] [--related-tickets] [--location]Create
storybloq issue update <id> [--status] [--title] [--severity] ...Update
storybloq issue meta get|set|unset <id> [path] [value]Manage custom passthrough metadata
storybloq issue delete <id>Delete

Notes and lessons

CommandDescription
storybloq note list · note get · note create · note updateBrainstorming and idea capture
storybloq lesson list · lesson get · lesson create · lesson update · lesson reinforceReusable patterns and anti-patterns
storybloq lesson digestCompact summary of all active lessons for skill injection

Handovers, blockers, snapshots

CommandDescription
storybloq handover list · handover latest · handover get <file>Session continuity documents
storybloq handover create --title --tldr ...Write a new handover
storybloq blocker list · blocker add · blocker clearExternal dependencies blocking progress
storybloq snapshot · storybloq recapCapture state and diff against the last snapshot
storybloq export [--phase <id>] [--all] [--format json|md]Self-contained project document

Federation (orchestrator projects)

CommandDescription
storybloq init --type orchestratorScaffold an orchestrator .story/ with a nodes map
storybloq node add <name> --path <dir> [--stack] [--role] [--depends-on] [--link]Register a node repo
storybloq node remove <name> [--force | --prune]Unregister a node (checks for dependents first)
storybloq node update <name> [--stack] [--role] [--depends-on] [--health]Update node metadata
storybloq node listTable of all configured nodes
storybloq config set-federation --allow-node-writesAllow orchestrator to write into node repos

MCP server reference

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

bash
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 walking up from the working directory to the nearest .story/ parent.

53 tools grouped by responsibility:

Read (no side effects)

storybloq_status · storybloq_phase_list · storybloq_phase_current · storybloq_phase_tickets · storybloq_ticket_list · storybloq_ticket_get · storybloq_ticket_meta_get · storybloq_ticket_next · storybloq_ticket_blocked · storybloq_issue_list · storybloq_issue_get · storybloq_issue_meta_get · storybloq_note_list · storybloq_note_get · storybloq_lesson_list · storybloq_lesson_get · storybloq_lesson_digest · storybloq_handover_list · storybloq_handover_latest · storybloq_handover_get · storybloq_blocker_list · storybloq_validate · storybloq_recap · storybloq_recommend · storybloq_export · storybloq_selftest

Write (mutate .story/)

storybloq_snapshot · storybloq_handover_create · storybloq_ticket_create · storybloq_ticket_update · storybloq_ticket_meta_set · storybloq_ticket_meta_unset · storybloq_issue_create · storybloq_issue_update · storybloq_issue_meta_set · storybloq_issue_meta_unset · storybloq_note_create · storybloq_note_update · storybloq_lesson_create · storybloq_lesson_update · storybloq_lesson_reinforce · storybloq_phase_create

Autonomous mode + review + observability

storybloq_autonomous_guide drives the autonomous state machine (PICK_TICKET -> PLAN -> PLAN_REVIEW -> WRITE_TESTS -> IMPLEMENT -> TEST -> CODE_REVIEW -> FINALIZE -> COMPLETE).

storybloq_review_lenses_prepare · storybloq_review_lenses_judge · storybloq_review_lenses_synthesize orchestrate the multi-lens review loop (requires @storybloq/lenses).

storybloq_session_report · storybloq_register_subprocess · storybloq_unregister_subprocess surface session health to the Mac app.

Federation (orchestrator projects)

storybloq_node_init bootstraps .story/ in a node repo from the orchestrator context.

storybloq_node_add · storybloq_node_list · storybloq_node_update manage the orchestrator's node registry.

<p align="center"> <img src="https://raw.githubusercontent.com/Storybloq/storybloq/main/assets/handover.png" alt="Handover timeline with AI-summarized date groups" /> </p>

Hooks

PreCompact (Claude-only auto-snapshot, set up by setup)

Runs storybloq snapshot --quiet before context compaction so recap always reflects the latest state. Manually:

json
{
  "hooks": {
    "PreCompact": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "storybloq snapshot --quiet" }]
    }]
  }
}

Skip with storybloq setup --client all --skip-hooks.

SessionStart (optional recap injection)

Auto-inject what changed since last snapshot:

json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "storybloq recap --format md" }]
    }]
  }
}

Library usage

typescript
import { loadProject } from "@storybloq/storybloq";

const { state, warnings } = await loadProject("/path/to/project");
console.log(state.tickets.length);           // all tickets
console.log(state.phaseTickets("p1"));       // leaf tickets in phase p1
console.log(state.umbrellaChildren("T-014")); // children of an umbrella

Full type definitions ship with the package (exports.types).

File format examples

Ticket (.story/tickets/T-001.json):

json
{
  "id": "T-001",
  "title": "Add search to sidebar",
  "type": "task",
  "status": "inprogress",
  "phase": "p2",
  "order": 10,
  "description": "Fuzzy match over ticket title + description.",
  "createdDate": "2026-04-12",
  "completedDate": null,
  "blockedBy": [],
  "parentTicket": null,
  "crossNodeBlockedBy": []
}

Issue (.story/issues/ISS-001.json):

json
{
  "id": "ISS-001",
  "title": "Drag handle hit target too small on trackpad",
  "status": "open",
  "severity": "medium",
  "components": ["mac-app"],
  "impact": "Dragging tickets on trackpad requires multiple tries.",
  "location": ["macos/Views/KanbanCard.swift:42"],
  "discoveredDate": "2026-04-15",
  "resolvedDate": null,
  "relatedTickets": []
}

Each record is its own file. IDs are sequential within type (T-001, T-002, ...). Relationships are single-canonical-owner: a ticket's blockedBy field points at blocker tickets, and the reverse (who-blocks-me) is derived by scanning.

Create operations are safe to run in parallel. ID assignment and the create write happen together under a project lock, so concurrent creators are serialized and each receives a distinct sequential ID. A create can never silently overwrite an existing record; under heavy simultaneous contention a creator fails loudly with an error rather than colliding.

Ticket and issue records preserve unknown JSON fields. Use storybloq ticket meta and storybloq issue meta to read or mutate those custom passthrough fields without touching core Storybloq fields. Values are JSON, and dot paths address nested objects, for example storybloq ticket meta set T-001 integration.linear '"ABC-123"'.

Example workflow

bash
# Initialize
storybloq init --name "my-app"

# Add the first phase
storybloq phase create --id bootstrap --name "Bootstrap" --label "PHASE 1" \
  --description "Get the app running end-to-end"

# Add a ticket
storybloq ticket create --title "Scaffold Next.js" --type task --phase bootstrap

# Start Claude Code, type /story, then work on it
# (or go autonomous: /story auto T-001)

# At the end of a session, commit your changes including .story/
git add .
git commit -m "T-001: scaffold Next.js"

# Session ends. Next session starts with /story and picks up with full context.
  • @storybloq/lenses - multi-lens code review MCP server. 8 specialized reviewers run in parallel and return structured verdicts.
  • Storybloq for Mac - native macOS app that watches .story/ and updates live while Claude works. Free on the Mac App Store.

Contributing

Issues and PRs welcome. For non-trivial changes, open an issue first so we can align on direction.

Development setup:

bash
git clone https://github.com/Storybloq/storybloq.git
cd storybloq
npm install
npm test
npm run build

License

PolyForm Noncommercial 1.0.0. Free for personal and noncommercial use. For commercial licensing, contact shayegh@me.com.

See LICENSE for the full text and NOTICE for the required copyright notice you must propagate if you redistribute.

Contributors

Showing top 2 contributors by commit count.

AmirShayegh

AmirShayegh

381 commits

j2webs

j2webs

1 commits

View all contributors on GitHub →

This article is auto-generated from Storybloq/storybloq via the GitHub API.Last fetched: 6/29/2026