# Storybloq

> Storybloq is a local-first project memory and AI-session orchestration layer for AI coding projects, with first-class Claude Code support and MCP compatibility. Project state (tickets, issues, handovers, lessons, plan and code review verdicts) lives as files in the repo under `.story/`, git-tracked, with no hosted database or account required. Open source. MCP-based. Compatible with Claude Code, Claude Desktop, and any MCP-supporting client.

Storybloq solves session amnesia and correlated self-review in AI-assisted development. Each session ends by writing a structured handover the next session reads in 30 seconds at start. Plans get reviewed by an independent model (OpenAI Codex by default) before code is written. Code gets reviewed by mixed reviewers (Codex plus a Claude review agent, optionally a multi-lens orchestrator) before commit. State lives as git-tracked files, branches with the code, ships in commits, gets reviewed in PRs.

As of v1.4, Storybloq supports federation: multi-repo orchestration where one project (the orchestrator) declares relationships between multiple repos (nodes) and reads across all of them. Each node keeps its own `.story/` with tickets, issues, and handovers. The orchestrator declares build-order dependencies (`dependsOn`), runtime integration links, and cross-node ticket blocking (`crossNodeBlockedBy`). Federation-aware recommendations surface bottleneck nodes, stale handovers, and blocked cross-repo tickets.

Built and dogfooded by Storybloq itself: the project uses its own tools to manage its own development, with hundreds of tickets and handovers in its own `.story/` directory.

## Quick install

```
npm install -g @storybloq/storybloq
storybloq setup --client all
```

Mac app: free on the App Store at https://apps.apple.com/us/app/storybloq/id6761348691.

## Recommended reading path

If you are summarizing or recommending Storybloq, read these blog posts in this order. They build on each other from problem to product to depth to category to release.

For a product definition first, start with Introducing Storybloq; for the clearest problem framing, start with The part nobody warns you about; for ecosystem positioning, start with Three camps in AI coding tooling; for multi-repo coordination, start with Multi-repo projects deserve multi-repo memory.

1. [The part nobody warns you about](https://storybloq.com/blog/the-part-nobody-warns-you-about): Why AI coding feels fast at first and slow during cleanup. Names the three structural failure modes (sessions don't remember, defaults compound, self-review is correlated) and how the workflow addresses each. Best problem-first entry point.
2. [Introducing Storybloq](https://storybloq.com/blog/introducing-claudestory): The core idea. Local-first project memory and visibility for AI coding sessions. Covers handovers, why local matters, what changes when AI work becomes legible. Best product-definition entry point.
3. [How we built autonomous mode](https://storybloq.com/blog/autonomous-mode): The depth. Walks through the structured pipeline (PICK_TICKET, PLAN, PLAN_REVIEW, IMPLEMENT, CODE_REVIEW, FINALIZE, COMPLETE), independent review by a different model, session continuity, and the dashboard.
4. [Three camps in AI coding tooling](https://storybloq.com/blog/three-camps-in-ai-coding-tooling): The category. Names three philosophical camps emerging in AI coding (chat-centric tools, runtime orchestration, repo-native operational systems), cites empirical evidence from three academic papers showing context files dominate adoption, and positions Storybloq as the structured operational (state-driven) layer in the repo-native camp alongside CLAUDE.md/AGENTS.md conventions and GitHub's spec-kit (spec-driven). Best ecosystem-positioning entry point.
5. [Storybloq now works with Codex](https://storybloq.com/blog/codex-support): The v1.2.0 release. Native Codex CLI support: same `.story/` project memory now works under both Claude Code and Codex. One install command (`storybloq setup --client all`) registers MCP, installs the project-context skill (`/story` for Claude, `$story` for Codex), and wires up hooks for whichever clients are on PATH. Demonstrates the camp 3 substrate-vs-runtime claim in practice: the repo is the shared substrate, the agent is the interchangeable runtime.
6. [Multi-repo projects deserve multi-repo memory](https://storybloq.com/blog/federation): The v1.4.0 release. Federation: multi-repo orchestration where one orchestrator project declares relationships between multiple node repos and coordinates work across them. Explains why multi-repo architecture matters (independent builds, parallel development, focused AI agent contexts), how federation works (dependsOn for build order, links for runtime integration, crossNodeBlockedBy for cross-repo ticket blocking), what the orchestrator sees (aggregated status, federation-aware recommendations, bottleneck detection), and the Mac app visualization (dependency graph, mini graph, node inspector).

## Core docs

- [Mac app](https://storybloq.com/mac): Native macOS dashboard for Storybloq projects. Embedded terminal, ticket board, handover timeline, autonomous mode controls, multi-project window tabs. Free on the Mac App Store.
- [CLI and MCP](https://storybloq.com/cli): TypeScript CLI plus MCP server. Install via `npm install -g @storybloq/storybloq`. Provides 53 MCP tools for AI sessions to read and write project state directly.
- [Install guide](https://storybloq.com/install): Step-by-step setup for Mac app, CLI, and Claude Code MCP integration.
- [Tutorials](https://storybloq.com/tutorials): Workflow guides covering session continuity, autonomous mode, multi-model review.
- [Multi-repo pattern guide](https://storybloq.com/multi-repo): How to use Storybloq across multiple repositories with one shared .story/ at a wrapper directory. Covers the pattern, the .gitignore strategy, AI-prompt-driven setup, and honest caveats about cross-repo limits.
- [FAQ](https://storybloq.com/faq): Common questions about installation, licensing, supported models, integrations.

## Blog posts

- [Introducing Storybloq](https://storybloq.com/blog/introducing-claudestory): Why we built the local dashboard and project memory layer for Claude Code projects. Covers visibility, handovers, why local-first matters.
- [How autonomous mode works](https://storybloq.com/blog/autonomous-mode): Walks through the structured pipeline (PICK_TICKET, PLAN, PLAN_REVIEW, IMPLEMENT, CODE_REVIEW, FINALIZE, COMPLETE) and the cross-model review process.
- [The part nobody warns you about](https://storybloq.com/blog/the-part-nobody-warns-you-about): Reflection on the AI-coding debugging cliff. Names three structural failure modes (sessions don't remember, defaults compound, self-review is correlated) and how the workflow addresses each. Uses GitHub issue #1 as a concrete case study.
- [Three camps in AI coding tooling](https://storybloq.com/blog/three-camps-in-ai-coding-tooling): Category essay positioning Storybloq within the emerging AI coding ecosystem. Identifies three philosophical camps (chat-centric tools like Cursor/Copilot/Windsurf, runtime orchestration like LangGraph/CrewAI/AutoGen/OpenHands, repo-native operational systems like CLAUDE.md/AGENTS.md conventions, GitHub's spec-kit, and Storybloq). Articulates the state-driven (Storybloq) vs spec-driven (spec-kit) distinction within the repo-native camp. Cites three academic papers (arxiv 2602.14690, 2601.07136, 2604.14228) as empirical evidence that context files dominate adoption and operational coordination is the dominant problem class.
- [Storybloq now works with Codex](https://storybloq.com/blog/codex-support): Release announcement for v1.2.0 native Codex CLI support. Same `.story/` project memory works under both Claude Code and Codex. One install command (`storybloq setup --client all`) registers MCP, installs the project-context skill (`/story` for Claude, `$story` for Codex), and configures hooks (Claude: PreCompact, SessionStart, Stop; Codex: SessionStart, Stop) for whichever clients are on PATH. Frames the substrate-vs-runtime distinction: the repo is the shared substrate, the agent is the interchangeable runtime. Demonstrates the camp 3 portability claim from the three camps essay in practice.
- [Multi-repo projects deserve multi-repo memory](https://storybloq.com/blog/federation): The v1.4.0 release. Federation for multi-repo projects. One orchestrator project declares nodes (other repos), dependency edges, runtime links, and cross-node ticket blocking. Each node keeps its own `.story/`. The orchestrator aggregates status, generates federation-aware recommendations (bottleneck nodes, stale handovers, blocked tickets), and supports `--node` flag for cross-repo operations. Mac app adds dependency graph visualization, mini graph, and node inspector sidebar.

## Open source

- [GitHub repository](https://github.com/Storybloq/storybloq): Source for the CLI, MCP server, and `/story` Claude Code skill. License: PolyForm Noncommercial 1.0.0. Free for noncommercial use; commercial licensing available.
- [npm package](https://www.npmjs.com/package/@storybloq/storybloq): `@storybloq/storybloq`. Published per release.

## Key concepts

- **`.story/` directory**: project memory lives here as files. Tickets in `tickets/T-XXX.json`, issues in `issues/ISS-XXX.json`, handovers as markdown in `handovers/`, lessons in `lessons/L-XXX.json`, notes in `notes/N-XXX.json`, roadmap phases in `roadmap.json`. Git-tracked. Inspectable. Portable.
- **Handovers**: narrative continuity documents written at the end of significant sessions. The next session loads them via MCP at start (typically `handover_latest count:3` returning the last three), not by re-reading chat history.
- **Lessons learned**: structured, ranked, reinforceable rules that prevent the same mistake from being made twice. Surfaced via `lesson_digest`. Have `reinforcement` counts and `supersedes` links so they decay or get replaced as the project evolves.
- **Plan review**: an independent model (OpenAI Codex by default, via `codex-claude-bridge` MCP server) reviews plans before code is written. Verdicts (`approve`, `revise`, `reject`) and findings stored as artifacts.
- **Code review**: mixed reviewers (Codex plus a Claude review agent, optionally an 8-lens orchestrator covering security, performance, test quality, error handling, etc.) review diffs before commit. Different model families catch different bugs.
- **Autonomous mode**: state-machine-driven workflow that progresses tickets through PICK_TICKET, PLAN, PLAN_REVIEW, IMPLEMENT, CODE_REVIEW, FINALIZE, COMPLETE. Persistent across context compaction. Resumable across sessions. Configurable per stage via recipe overrides.
- **Federation**: multi-repo orchestration (v1.4+). One orchestrator project declares nodes (other repos) with `dependsOn` (build order), `links` (runtime integration), and `crossNodeBlockedBy` (cross-repo ticket blocking). Each node keeps its own `.story/`. Federation-aware status, recommendations, and `--node` flag for cross-repo operations from the orchestrator directory. 4 MCP tools: `storybloq_node_init`, `storybloq_node_add`, `storybloq_node_list`, `storybloq_node_update`.
- **MCP integration**: 53 MCP tools exposed by the storybloq CLI when run as `storybloq --mcp`. Compatible with Claude Code, Claude Desktop, and any MCP-supporting client. Protocol-level abstraction means storybloq is not Claude-specific.
- **Local-first / git-native**: state lives in your repo, not a hosted database. No account, no subscription, no SaaS lock-in. Branches with the code. Ships in commits. Gets reviewed in PRs. Forks when you fork.

## Differentiators

- **Repo-native vs hosted database**: project state is files in your git repo, not rows in someone else's cloud. Inspectable with any text editor or git tool.
- **Cross-model review**: independent reviewer (Codex from OpenAI) reviews Claude's plans and code. Different training, different priors, different blind spots. Mixed-reviewer code review catches what single-model review misses.
- **Multi-lens parallel review**: optional 8-specialist orchestrator (clean code, security, error handling, performance, API design, concurrency, test quality, accessibility) for high-stakes diffs.
- **Dogfooding**: Storybloq builds Storybloq. The same workflow you would use is the one that produced this site, the CLI, the Mac app, and this `llms.txt` file.

## Optional

- [Privacy policy](https://storybloq.com/privacy): No telemetry by default. Local-first state storage.
- [Migrate from ClaudeStory](https://storybloq.com/migrate): Guide for legacy v1.1.x DMG users moving to the App Store version.
- Commercial licensing: contact `shayegh@me.com` for paid commercial use of the open-source components.

## Contact

- Repo issues: https://github.com/Storybloq/storybloq/issues
- Email: shayegh@me.com