Session lifecycle
stateDiagram-v2 [*] --> Open: a flow starts Open --> Finished: finish Finished --> Closed: shipping runs session close note right of Finished : You choose merge, pull request or keep Closed --> Deleted: merged Closed --> Open: the same slug starts again Deleted --> [*]
How it works
Section titled “How it works”Three steps end a session. Each does one job.
| Step | Who runs it | What it does | Your branch |
|---|---|---|---|
superlite-cli finish |
the run, when it ends | Marks the session run:finished. Moves the run’s files into .superlite/runs/. |
untouched |
superlite-cli session close |
shipping, after you choose | Archives the session and unregisters it. Saves uncommitted work. Puts the checkout back on the base branch. | kept with --keep-branch, which shipping passes |
/superlite:merged |
you, after a pull request merges | Asks gh whether the pull request merged. Fast-forwards local main. Closes the session if it is still listed. Deletes its archive and the local branch. |
deleted, only if it is the merged one |
/superlite:merged never pushes and never touches the remote branch.
Where uncommitted work goes
Section titled “Where uncommitted work goes”A superlite build leaves its work uncommitted. At shipping you choose to commit it to the session branch or leave it. If you leave it, close saves it, tracked files and untracked files, on the private ref refs/superlite/wip/<slug>. It does not appear in git stash list. Start the same slug again and superlite applies it back; if it cannot apply cleanly, it stays on the ref. /superlite:merged asks before it discards work found there.
What close does, by where the session lived
Section titled “What close does, by where the session lived”| Where it lived | What close does |
|---|---|
| Main checkout | Saves the work, parks the run files, switches back to the base branch. If that branch is checked out elsewhere, or a merge or rebase is running, it refuses and changes nothing. |
| Worktree superlite cut | Saves the work the same way, then removes the worktree. It deletes the branch only if the branch merged cleanly, nothing was saved and there was no run. |
| Worktree Claude Code made | Archives the run files and the row. The worktree, its files and its branch stay as they are. Leave it with ExitWorktree. |
With --untracked keep and untracked files present, close on a worktree superlite cut saves nothing, leaves the worktree in place and keeps the row.
Example: one session, from request to merged
Section titled “Example: one session, from request to merged”Take the session behind PR #56, the prototype sandbox change. Its slug is proto-sandbox.
-
You ask for the change.
Claude Code · ~/superlite ❯ /superlite:start Feature prototypes run in a sandbox, not a worktreeUnderneath, the flow opens the session (state Open): the branch
superlite/sessions/proto-sandbox, cut frommain. Plan, build and review all happen on that branch. The build leaves its work uncommitted, by design. -
The run ends. You read the report and see one line about the session.
Claude Code · ~/superlite session: proto-sandbox finishedrun: archived to .superlite/runs/<run>Underneath,
superlite-cli finishmarks the session Finished and moves the run’s files into.superlite/runs/. Your branch is untouched. -
You decide: commit or leave? Shipping asks once.
Claude Code · ~/superlite Commit the work to superlite/sessions/proto-sandbox?❯ 1. Commit to superlite/sessions/proto-sandbox2. Leave uncommittedUnderneath, a commit lands on the session branch only, never on
main. Without one, the next question offers only “Keep the branch”.gitGraph commit id: "main" branch "superlite/sessions/proto-sandbox" commit id: "the finished work"
-
You decide: merge, pull request or keep? The question carries the test count and the diff summary. PR #56 reported 2,342 tests passed.
Claude Code · ~/superlite ❯ 1. Merge locally into the base branch2. Push and open a pull request3. Keep the branch as isUnderneath, option 2 pushes the branch and runs
gh pr createagainstmain. Then shipping runssuperlite-cli session close --keep-branch: the session is Closed,~/superliteis back onmain, and the branch stays for the PR.Directorysuperlite/ back on main
Directory.superlite/
Directorysession-store/
Directoryproto-sandbox/ the archived session, kept until the merge
- …
Directoryruns/ the finished run
- …
-
The pull request merges on GitHub. Nothing happens in superlite. The archive and the branch wait.
On GitHub the pull request now shows as Merged into
main. -
You tell superlite.
Claude Code · ~/superlite ❯ /superlite:merged 56PR #56 merged: https://github.com/iha2/superlite/pull/56merge commit c43cad7; local main fast-forwardedsession proto-sandbox closed; branch superlite/sessions/proto-sandbox deletedUnderneath,
/superlite:mergedasksghwhether the pull request really merged and checks that the local branch holds nothing the pull request did not. Only then does it fast-forwardmain, drop the archive and delete the local branch (state Deleted). It never pushes and never touches the remote branch.gitGraph commit id: "main" branch "superlite/sessions/proto-sandbox" commit id: "the finished work" checkout main merge "superlite/sessions/proto-sandbox"
What you end up with: the change on main, the local branch and session-store/proto-sandbox/ gone, and .superlite/runs/ still holding the run for the report history. The remote branch is yours to delete. If you had left the work uncommitted, the close line would end with (wip refs/superlite/wip/proto-sandbox) and /superlite:merged would ask before discarding it.
Good to know
Section titled “Good to know”- Starting the same topic again keeps its run. Starting a different topic copies the unfinished files to
.superlite/runs/and leaves them live. /superlite:stoppauses a run and/superlite:resumecontinues it. Neither changes the session.superlite-cli session use --slug Sswitches sessions by hand. On a conflict, resolve it, rungit add, and rerun with--continue.superlite-cli session discard --slug Sdrops a session’s archive, saved work and branch. It is the step/superlite:mergeduses.
See where a session works in Worktrees, or go back to Sessions. Other commands are on Commands.