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

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-skill
```

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 architecture to depth.

For a product definition first, start with Introducing Storybloq; for the clearest problem framing, start with The part nobody warns you about.

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 Claude Code projects. 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.

## Core docs

- [Mac app](https://storybloq.com/mac): Native macOS dashboard for Claude Code 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 43 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.
- [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.

## 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.
- **MCP integration**: 43 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