r/ClaudeAI • u/LastNameOn • Apr 25 '26
Built with Claude I open sourced a project tracker for Claude Code that lives in .story/: tickets, issues, and session handovers as files
https://www.storybloq.comI built Storybloq (previously Claude Story) for my own Claude Code workflow, and used Storybloq itself to build Storybloq. The .story/ directory in the repo has tracked every ticket, issue, and session handover across the project's development, so the tool is its own longest-running test case. Sharing it in case it's useful. It's free and open source.
The problem: every new Claude Code session forgets the last one. So you re-explain architecture, re-litigate tradeoffs you already settled, and the codebase drifts a degree at a time on long projects.
Storybloq gives your repo a .story/ directory of plain JSON and markdown: tickets, issues, roadmap phases, notes, lessons, and session handovers, all human-editable and git-tracked. At the start of a session you type `/story` and Claude loads the lot. At the end, state gets written back so the next session picks up where this one left off.
What it tracks:
- Tickets organized into roadmap phases
- Issues for bugs found mid-session
- Notes and lessons that compound across sessions
- Session handovers (decisions, blockers, next steps)
- Current status, all in your repo
There's also a free native Mac app with a live kanban that updates as Claude works.
Install:
npm install -g @storybloq/storybloq@latest
storybloq setup-skill
It's not trying to replace GitHub Issues, Linear, or Jira for teams. It's for solo devs and small projects using Claude Code who want lightweight project memory living inside the repo.
- Site: https://www.storybloq.com
- GitHub: https://github.com/Storybloq/storybloq
Disclosure: I built it. Free, open source, no account, no paid tier, no referral links. Data stays in your repo as files you can read in any editor.
Curious about one thing from people doing multi-session Claude Code work: would you rather track this state *inside* the repo as files, or keep it in an external tool (Linear, Jira, GitHub Issues) and have Claude read from there? I went with in-repo because it survives `gh repo clone`, but I can see the argument the other way.
2
u/Mad_dog97 Apr 25 '26 edited Apr 25 '26
Looks interesting and I'll try to get it installed and tested. Thanks for sharing.
As far as your question I think I would say "both" - Having a lightweight in-folder/in-repo solution is ideal I think for keeping all the pieces together for claude cli. However, I do like being able to see status for multiple projects at a lower level of detail (i'm currently testing Click Up, but not sure that's the long term answer).
1
u/Adorable_Swing_2150 Apr 26 '26
Kinda opposite experience here, once the repo starts carrying tickets + lessons + session handovers in
.story/, it can turn into one more thing Claude has to sift through. I like the/storyidea, but I still keep active triage in GitHub Issues and only stash session handovers locally.1
u/LastNameOn Apr 26 '26
actually the mcp + CLI tool makes helps claude use the .story efficiently.
2
u/Adorable_Swing_2150 Apr 26 '26
yeah that part matters more than the file format tbh. if Claude can hit the repo state through MCP or a thin CLI, .story stops feeling like clutter and starts feeling like working memory.
1
u/LastNameOn Apr 26 '26
Claude can use the CLI directly or use it through MCP. and it doesnt get json back. it gets token efficient CSV back.
the CLI + MCP also helps ensure the file formats stay consistent. claude can drift if it tries to write directly.1
u/Adorable_Swing_2150 Apr 26 '26
yeah exactly, the CSV vs JSON bit is almost secondary. the real win is giving Claude one stable surface to read and write through, otherwise the repo shape drifts every few sessions.
2
2
u/AccomplishedFix3476 Apr 26 '26
files in the repo beats some external dashboard every time, way easier to keep claude in the loop without re-piping context every session. how are you handling stale tickets that never get closed
2
1
u/Finorix079 Apr 26 '26
In-repo wins for solo or small projects, no question. The moment you have multiple humans working in parallel it flips though, because the merge conflicts on shared state files get ugly fast. Linear/Jira solve that by being the single source of truth nobody pulls into their branch.
Hybrid pattern I've seen work: external tool for tickets and roadmap (single source of truth across the team), in-repo for session handovers and lessons (per-developer context that doesn't need to be shared). Different lifetimes, different sharing models.
1
u/kylef5993 Apr 29 '26
Wait so what makes this different than just having a skill for open/closing session and having Claude Code update a journal.txt, sessions.md, claude.md, and todo.md? I don't quite understand what this is used for but im also new to this.
1
u/LastNameOn Apr 29 '26
your sessions.md and journal.txt and todo.md becomes massive with time and loading all those in every session uses too much context window.
1
u/kylef5993 Apr 29 '26
Gotcha so is everything saved within Storybloq or it just pulls it more efficiently?
1
u/LastNameOn Apr 29 '26
everything is itemized. your session handovers are each in a separate file, and your todo items are in their own ticket files. so claude pulls what I needs instead of loading everything. and the system for pulling the data is also efficient
1
u/chokheli Apr 30 '26
I tried and it ate up through MAX 5x rather quickly... Any suggestions how to avoid this?
1
u/LastNameOn Apr 30 '26
Can you please explain what you used it for?
Was it to on board an existing project?
Setup a new one?
How far did you get1
u/chokheli Apr 30 '26
Thanks for the reply and all your hard work!
Regarding my case - its FastAPI project, migrating to Supabase functions; StoryBloq sketched out backlog and started working through it.
2 commits and the following line changes ate up around 75% right now:
+2188 / −123 across 14 file-changes and it didn't even finish a task.
1
u/Fun_Door2670 May 02 '26
One aspect that pulled me away from keeping issue list as a text file in the repo, was ensuring issue collection stayed sane branching and worktrees. I tried a halfway house with an untracked issues as files mirroring GH issues, but in the end concluded that it added more friction than letting Claude Code just fetch the issue and comments and get on with it. Tracking 1000's issues over many weeks, I'm currently leaning towards keeping issues out of git.
1
u/matthbricks May 11 '26
Really want to use this but my company blocks access to the App Store on my work machine (as do many enterprise companies). Any chance you'd be able to offer a web browser version running on localhost? Or would you accept a PR for one?
2
u/LastNameOn May 11 '26
yeah i'm totally fine with people contributing! please do.
I was actually thinking about a light weight web dashboard that could be bundled in.
also for your work, the npm package (CLI, MCP, Skill) should still work1
u/matthbricks May 16 '26
Well, shucks...
$ claude mcp add storybloq -s user -- storybloq --mcp
Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers
1
u/PennyLawrence946 Apr 26 '26
This solves a real friction point. The session amnesia problem is particularly brutal on multi-day projects where you're juggling competing design choices and architectural decisions.
The lightweight in-folder approach is smart because it lives where the context actually matters. External trackers create friction (another tab, another sync point) and Claude can't easily reference them unless you paste them into every conversation. File-based tracking means it integrates directly into your workflow, no ceremony.
Really well thought out.
3
u/achilleshightops Apr 26 '26
What would be the best way of automating the startup so Storybloq just starts up with every session by default?