A file convention
A .story/ directory of JSON and markdown keeps tickets, decisions, lessons, and handovers beside the code. Tracked by git. Readable by any AI.
Learn about the CLI →The repo-native operational layer for Claude Code and Codex.
Storybloq makes autonomous software work recoverable, inspectable, and provable.
Durable project state survives session boundaries and context compaction. Repo-native files and the Mac app make the work visible. Independent review gates preserve the evidence behind what ships.
Local-first. Plain files. Git-trackable. No account.
New here? Check out the tutorials
Now also: Codex
The problem
Two ways to write code with a machine.
Same developer. Same AI. Same hour of the afternoon. The difference is whether the work survives the session, stays visible while it runs, and carries evidence before it ships.
Monday, 9:14 am
Vibe coding.
Start session. Read nothing.
Ask the AI what you should work on. It hallucinates context from three files and a prayer.
Produce code that may or may not fit. The architecture drifts by a degree. You won't notice for a week.
Close the tab. The session ends. Everything it learned dies with it.
Tomorrow you will have the same argument about the same function.
Monday, 9:14 am
Agentic development.
- i.The AI reads your spec, latest handover, open issues. Knows exact state.
- ii.It plans the work. A second AI reviews the plan.
- iii.You implement. Both AIs review the code.
- iv.You commit. A handover is written.
- v.Next session picks up where this one left off.
What it is
Three pieces. One idea.
The files make the work recoverable. The app makes it inspectable. The review loop makes it provable.
A native Mac app
See tickets, issues, handovers, and live session state while Claude Code or Codex works. The app watches the same repo-native record your agents use.
See the Mac app →A review loop
An optional independent reviewer challenges plans and code. Verdicts and findings remain attached to the work as evidence you can inspect.
See how it works →The system behind the promise
- .story/ folder
- The project memory
- CLI
- Creates and manages the memory
- MCP server
- Lets Claude Code and Codex read and update it
- /story or $story skill
- Loads context at session start
- Mac app
- Visualizes live project state
- Autonomous mode
- Optional ticket execution
- Review loop
- Optional second-AI critique
Working across multiple repos? See the multi-repo pattern.
The Mac App
See what your agent is doing in real time
A native Mac app that shows tickets, issues, and session handovers while Claude Code or Codex works. The board updates live as project files change.
“Most AI tools try to make the model smarter. Storybloq makes the system around the model smarter.”
Local to the project
No server, no account. Everything stays in your repo.
Updates in real-time
The board reflects what your agent is doing right now. Every change shows up instantly.
How it works
How it works.
1
Init
Run Storybloq init in your project to create .story/, then run setup once to register the MCP server with Claude Code and Codex.
storybloq init && storybloq setup --client all2
Work
Type /story in Claude Code or invoke $story in Codex at the start of each session. Your AI client loads your tickets, issues, roadmap, handovers, and lessons learned. It knows what was built, what's blocked, and what to do next.
/story # or $story in Codex3
Track
Create tickets for planned work, log issues for bugs you find, and capture ideas as notes. Then ask Claude to work on them.
4
Handover
At the end of a session, state is captured. Decisions, blockers, and next steps are preserved for the next session.
5
Dashboard
Open the Mac app to see live status: tickets in progress, issues discovered, roadmap phases, and session handovers.
How it differs
Different from the tools that look similar.
Storybloq does not replace your instructions, issue tracker, or coding client. It adds durable execution state and review evidence around them.
vs. CLAUDE.md
CLAUDE.md tells Claude how the project works. Storybloq tells Claude what just happened.
CLAUDE.md is static project guidance. Storybloq is changing project state: what was done, what is blocked, what decisions were made, what Claude learned, and what should happen next.
vs. GitHub Issues / Linear
GitHub Issues and Linear are for human teams. Storybloq is for AI sessions.
GitHub Issues and Linear are for human teams coordinating work. Storybloq is for AI sessions reading and writing project state directly. Different audience, different artifacts.
vs. AI IDEs and context windows
AI IDEs help a model inspect code in the current session. Storybloq preserves project state across sessions.
Cursor, Copilot, and similar tools help a model inspect and edit code within one session. Storybloq preserves project state across sessions as repo-native files: decisions, blockers, tickets, lessons, handovers.
Trust
Your project memory stays with your project.
Local .story/ files
JSON files in your repo, tracked by git, readable in any text editor.
No extra account. No hosted sync.
No server, no API key. Optional anonymous analytics and crash reports are off by default. You can opt in on first launch or in Settings.
Works with the AI client you already use
Storybloq sits on top of your existing Claude Code or Codex workflow. No new IDE, no migration.
Autonomous mode is optional
Use it as a daily dev assistant. Turn on autonomy when the work is well-defined and you want hands-off execution.
Read the work
The story, in field notes.
Six posts that build the picture from problem to product to depth to category to multi-repo.
Install
One command. Three places.
$npm install -g @storybloq/storybloq@latest
$storybloq setup --client all
# that's it. your next session knows the last one.
Free. Ships through the Mac App Store. Your data stays in your repo.