A reference for how my Claude Code sessions start, save, land and pick up again.
Why I built it
I'm an accidental developer.
I started building apps with Claude with no experience of git or GitHub. I quickly ended up in a mess: work not saved, branches I didn't understand, steps I forgot to do.
I also needed to move fast. My projects are complex, with several streams of work, often on the same code at the same time.
I'm dyslexic and I have ADHD. I forget things and I get distracted. Sometimes I don't touch a project for weeks, and when I come back I need to see exactly where it got to. That's why there's a dashboard: one page showing everything that's open and what stage it's at.
After many months of trial and error, this is what I ended up with.
What it gives me
Two commands to remember: /workon to start, /wrap to stop.
Nothing is lostMy memory, history and context are saved automatically, every turn.
Git looks after itselfCommits, pushes, branches and merges happen for me.
Work in parallelAs many workstreams as I like in one repo, at the same time, each in its own copy so they don't trip over each other.
How it works
One session, start to finish
Each conversation gets a name like om-pipeline-v12: the workstream, then a number. /wrap ends one, /workon om-pipeline-v13 starts the next.
The handoff is what lets a new conversation pick up cold. It says where things are, what's next and what's waiting.
Many workstreams, one repo
Each workstream works in its own copy of the repo (a worktree) on its own branch. Main is locked, so nothing is edited there by accident.
A land merges main into the branch first. If two workstreams clash, the land stops that branch and says why. Main never gets half-merged work.
A workstream can't write on another workstream's board. It drops a note instead, and that workstream's next /workon picks it up.
Quick reference
I type
What happens
/workon <name>-v<N>
Lands this workstream's finished work in the background, briefs me, then opens a private copy once I say go.
/wrap
Saves the session: handoff, ledger entry, board ticks, then marks the work ready or in progress. Work with failing or untested code is never marked ready.
/land
Shows what's ready across the repo, I pick, it lands. Only I start it.
/quickfix <what>
A small fix of a few files: temporary copy, the change, landed, cleaned up. One step.
/dashboard
Rebuilds the dashboard: every workstream, which repo it's in and where it's up to.
/recall <workstream> <question>
Asks the past conversations a question, for example "what did we decide about X".
/repo-health
A snapshot of a repo: its worktrees, branches, unlanded work and open sessions.
/flow-help
Shows this quick reference.
The pieces
Piece
What it is
Workstream
One piece of ongoing work, with a short name like om-pipeline. It runs across many conversations.
Worktree
A private copy of the repo for one conversation, on its own branch. Locked to that window while it's open.
Handoff
HANDOFF-<name>.md. Where things are now: status, next step, what's pending, standing decisions.
Board
BOARD-<name>.md. The phases and their items, plus an Inbox for new ideas. Created when a plan is approved.
Ledger
docs/ledger.md. One entry per conversation: what happened. The only history.
Router
HANDOFF.md. Built at every land: one line per workstream with its status. Never edited by hand.
Notes
A message from one workstream to another, held outside the repo until the other one's next /workon.
Archive
A copy of every conversation, grouped by workstream, made every turn. /recall searches it.
Dashboard
One local page listing every workstream, its repo and where it's up to.
Land
Moving finished work onto main: merge main in, squash into one commit, push, remove the copy.
What runs by itself
When
What
Session start
A short report on the repo's state.
Every turn
The work is committed and pushed (in a worktree), and the conversation is copied to the archive.
Before a tool runs
Main stays locked; commits carrying a secret or a huge file are blocked.
Before compacting
An emergency save.
75% of context used
One nudge to wrap soon.
A plan is approved
A reminder to create the board.
The notice board
Some things are true right now, and every workstream needs to know them before it acts: "don't ship the image until Sunday's walk is read", or "2.7.0 went out this morning". Each repo has one notice board for these.
The board lives outside the repo, so a notice is live the moment it's posted. No land is needed.
What goes where
The message
Where it goes
A rule for good
The repo's CLAUDE.md. Every workstream follows it, every time.
True right now
The notice board. Every workstream it concerns sees it before it acts.
A job for later
A note to one workstream. It picks it up at its next /workon.
When a notice is cleared, Claude asks me if it's permanent. If it is, it moves to CLAUDE.md.
Four kinds of notice
Kind
What it means
When it ends
HOLD
Don't ship or touch something until a condition is met.
When it's cleared by hand.
BEFORE-SHIP
Do something before the next ship.
When it's cleared by hand.
SHIPPED
Something went out, and it may matter to you.
By itself, after 3 days.
HEADS-UP
Anything else happening right now.
By itself, after 3 days.
A notice is for everyone, or for the workstreams it names. A hold open for a week or more is flagged, so someone checks it's still true. Another workstream's hold is never cleared without my yes.
When a session sees a notice
When
What I see
/workon
Every open notice for this workstream, first in the briefing. A workstream started later sees them too.
My next message
Anything posted while I was working. The work carries on.
I talk about shipping
Every open hold again. Claude asks me before any ship step, and posts a SHIPPED notice after it.
A ship step
With a hold open, the step stops once and Claude asks me. That includes a ship script Claude writes for me to run.
/wrap
This workstream's own notices, to check they're still true. Anything this session shipped, held or gated gets posted.
Only a ship step is ever stopped. A notice never interrupts a build.
The one rule
Workstreams never message each other directly (SendMessage). They post a notice instead, with --for when it concerns only one of them. A direct message dies with the conversation. A notice is still there for the next session.
Scripts, skills and files
Scripts
The commands keep the judgement. The scripts do the mechanics, so the same steps run the same way every time.
Script
Job
flow-workon.mjs
The facts for the briefing, then opening or resuming the worktree.
flow-wrap.mjs
The save at the end of /wrap: commit, push, ready or in progress.
flow-land.mjs
The only way work reaches main. One land at a time per repo.
flow-drop.mjs
Notes between workstreams: add, list, deliver.
flow-notice.mjs
The notice board: post, clear, list.
flow-dashboard.mjs
Builds the dashboard.
flow-transcript-sweep.mjs
Rescues conversations a removed worktree left behind.
flow-worktree-quarantine.mjs
Copies a worktree's untracked files to safety before it's removed.
flow-publish-guide.mjs
Publishes this page.
Skills and agents
Name
Job
session-historian
The agent behind /recall. Reads the archive on its own, so my conversation stays lean.
dev-project
Sets up and edits boards by hand when one isn't born from a plan.
Inside a typical repo
Two workstreams, om-pipeline and onboarding, each with one conversation open.
my-app/
├── .claude/
│ ├── flow.yaml switches Session Flow on
│ ├── branch-state/ ready or in progress, kept on each branch
│ └── worktrees/
│ ├── om-pipeline-v12/ a private copy for one open conversation
│ └── onboarding-v4/
├── docs/
│ ├── ledger.md one entry per conversation
│ └── notes/ long notes, linked from a board
├── _handoff-archive/ handoffs of finished workstreams
├── HANDOFF.md the router: every workstream's status
├── HANDOFF-om-pipeline.md where this workstream is now
├── BOARD-om-pipeline.md its phases and Inbox
├── HANDOFF-onboarding.md
├── BOARD-onboarding.md
└── src/ … the app itself
On this machine
Where
What
~/.claude/
The commands, scripts, hooks and this guide.
~/.claude/flow-drops/
Notes waiting for their workstream.
~/.claude/flow-notices/
One notice board per repo.
~/.claude/dashboard/
The dashboard page.
The archive folder
Every conversation, by repo and workstream. Set by FLOW_ARCHIVE_DIR.