by Storybloq
Cross-session context for Claude Code. CLI + MCP server + /story skill that tracks tickets, issues, handovers, and roadmap in a .story/ directory.
# Add to your Claude Code skills
git clone https://github.com/Storybloq/storybloqAI 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.
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.
storybloq - inspect and mutate .story/ from the terminal./story loads project state at the start of every session so Claude Code picks up exactly where the last session left off..story/ and updates live while Claude works (separate product, free on the App Store).npm install -g @storybloq/storybloq@latest
storybloq setup-skill
Requires Node.js 20+ and Claude Code. Package lives on npm at @storybloq/storybloq; releases are tagged on this repo at github.com/Storybloq/storybloq/releases.
setup-skill installs the /story skill globally to , registers this package as an MCP server, and configures a PreCompact hook that auto-snapshots state before context compaction. Re-running it is safe.
No comments yet. Be the first to share your thoughts!
~/.claude/skills/story/npm install -g @storybloq/storybloq@latest
storybloq setup-skill
Same two commands as a fresh install — @latest pulls the newest version, and re-running setup-skill refreshes the /story 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; setup-skill is the recommended install).
cd your-project
storybloq init --name "your-project"
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/.
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.
All commands accept --format json|md (default md). Pipe JSON through jq for scripting, read the markdown variant directly.
| Command | Description |
|---------|-------------|
| storybloq init [--name] [--force] | Scaffold .story/ in the current directory |
| storybloq status | Project summary with phase statuses, counts, and risks |
| storybloq validate | Reference integrity + schema checks |
| storybloq setup-skill [--skip-hooks] | Install /story skill + register MCP + PreCompact hook |
| storybloq recommend --count N | Context-aware work suggestions |
| Command | Description |
|---------|-------------|
| storybloq phase list | All phases with derived status (status is computed from tickets, never stored) |
| storybloq phase current | First non-complete phase |
| storybloq phase tickets --phase <id> | Leaf tickets for a phase |
| storybloq phase create --id --name --label --description [--summary] --after/--at-start | Create a phase |
| storybloq phase rename <id> [--name] [--label] [--description] [--summary] | Update phase metadata |
| storybloq phase move <id> --after/--at-start | Reorder |
| storybloq phase delete <id> [--reassign <target>] | Delete (reassign contained tickets) |
| Command | Description |
|---------|-------------|
| storybloq ticket list [--status] [--phase] [--type] | List leaf tickets (umbrellas excluded) |
| storybloq ticket get <id> | Full ticket detail |
| storybloq ticket next | Highest-priority unblocked ticket |
| storybloq ticket blocked | All currently blocked tickets |
| storybloq ticket create --title --type --phase [--description] [--blocked-by] [--parent-ticket] | Create |
| storybloq ticket update <id> [--status] [--title] [--phase] [--order] ... | Update |
| storybloq ticket delete <id> [--force] | Delete |
| Command | Description |
|---------|-------------|
| 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 delete <id> | Delete |
| Command | Description |
|---------|-------------|
| storybloq note list · note get · note create · note update | Brainstorming and idea capture |
| storybloq lesson list · lesson get · lesson create · lesson update · lesson reinforce | Reusable patterns and anti-patterns |
| storybloq lesson digest | Compact summary of all active lessons for skill injection |
| Command | Description |
|---------|-------------|
| 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 clear | External dependencies blocking progress |
| storybloq snapshot · storybloq recap | Capture state and diff against the last snapshot |
| storybloq export [--phase <id>] [--all] [--format json\|md] | Self-contained project document |
Register with Claude Code (done automatically by setup-skill):
claude mcp add storybloq -s user -- 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.
43 tools grouped by responsibility:
storybloq_status · storybloq_phase_list · storybloq_phase_current · storybloq_phase_tickets · storybloq_ticket_list · storybloq_ticket_get · storybloq_ticket_next · storybloq_ticket_blocked · storybloq_issue_list · storybloq_issue_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 · `s