Worktrees
flowchart TD
S["A flow starts"] --> Q{"What kind of work?"}
Q -->|"feature integration"| W1["Own worktree, always"]
Q -->|"review of another branch"| R{"Where is that branch?"}
R -->|"checked out here"| IP1["Work in place"]
R -->|"in another folder"| RD["Go to that folder"]
R -->|"nowhere"| W2["New worktree on it"]
Q -->|"anything else"| O{"Another session open here?"}
O -->|"no"| IP2["Work in place, new branch"]
O -->|"yes"| A{"You decide: move it out?"}
A -->|"yes"| W3["Each session gets a worktree"]
A -->|"no"| N["Nothing changes"]
How it works
Section titled “How it works”Think of your project folder as a desk. A branch is the job laid out on it. Switching jobs means clearing the desk. A worktree gives you a second desk: git checks out another branch into another folder, and both desks share one history. Two chats can then work at once without touching each other’s files. For example, a docs rewrite and a bug fix each get a folder, and neither sees the other’s half-finished edits.
By default superlite uses one desk. Sessions take turns in your main checkout. It adds a desk in two cases: a second chat starts while the first session is open, and a feature reaches its integration build. Worktrees live under .claude/worktrees/, which git never shows because superlite lists it in .git/info/exclude.
Directorysocial/ your main checkout
Directory.claude/
Directoryworktrees/
Directorysessions-export/ a session superlite moved out
- …
Directorysessions-login-fix/ a session superlite cut
- …
Directoryexport-int/ a feature’s integration build
- …
Directorymerge-main/ temporary, while shipping merges
- …
Directory.superlite/
Directorysandboxes/ not worktrees: prototype folders
- …
Older sessions may sit under .superlite/worktrees/sessions/<slug>. They keep working.
The move question
Section titled “The move question”When a new flow starts and your main checkout holds an open session, superlite does not touch that session on its own. It asks first, and changes nothing until you answer:
ASK move slug=export: export moves from the main checkout to /work/social/.claude/worktrees/sessions-export; its chat must be idle- Yes moves
export, with its run files and uncommitted work, into its own worktree. Your main checkout goes back to the base branch, and the new topic gets a worktree too. If anything fails, superlite puts everything back. - No stops here. Nothing changes, and the new session does not start. Finish or close the open session, then start again.
Answer yes only when the first chat is idle, because its files move. superlite may first ask what to do with untracked files: stash them with the session, or keep them in the main checkout.
If the open session is already on the base branch, it stays, and only the new session gets a worktree. superlite asks nothing.
The integration worktree
Section titled “The integration worktree”A feature runs twice. The prototype lives in a sandbox, a plain folder. After you approve it, the integration build gets its own worktree, named after the topic with -int.
Entering a worktree under Claude Code
Section titled “Entering a worktree under Claude Code”A new worktree is a different folder, so your chat has to step into it. Follow the line superlite prints:
session: create EnterWorktree name=<n> base=<ref>: Claude Code makes the worktree. CallEnterWorktree name=<n>, then rerun the same command inside it. superlite adopts the worktree.session: enter EnterWorktree path=<abs>: superlite already cut it, for example because your main checkout is not on the base. CallEnterWorktree path=<abs>.ASK branch-name: asked once. Keep Claude’sworktree-<slug>, usesuperlite/sessions/<slug>, or give a pattern with{slug}.
Other tools: cd to the path on the SESSION worktree= line.
Example: this docs session moves to its own desk
Section titled “Example: this docs session moves to its own desk”This docs site was built in a session called docs-site, in the main checkout ~/superlite, on the branch superlite/sessions/docs-site. Then a second piece of work started next to it.
-
A second run starts in the same folder. The two would share one
.superlite/and one checked-out branch.Chat 2 · ~/superlite ❯ /superlite:feature <your next request>Underneath,
session ensurefinds the open session and does not touch it unasked. It asks you. -
You decide: move the docs session out? You check that the docs chat is idle, then answer.
Chat 2 · ~/superlite Move session docs-site out of the main checkout into~/superlite/.claude/worktrees/sessions-docs-site? Its chat must be idle.❯ 1. Yes2. NoUnderneath, the question is the
ASK moveline from the move question. No leaves everything as it is and the new run does not start. -
superlite moves the session. It adds a worktree on the existing branch and moves the run files and uncommitted work into it. A failure puts everything back.
Directorysuperlite/ main checkout
Directory.claude/
Directoryworktrees/
Directorysessions-docs-site/ the docs session, on superlite/sessions/docs-site
- …
-
The docs chat steps over. Its old folder no longer holds the session, so its status line says so.
Chat 1 · ~/superlite superlite session: docs-site moved to ~/superlite/.claude/worktrees/sessions-docs-site — move the agent root there❯Underneath, git allows a branch in only one folder. Under Claude Code the chat calls
EnterWorktree path=<abs>; elsewhere youcdthere. It carries on with the same plan and files. -
Later, a feature builds in a worktree of its own. A “People you may know” feature tries its prototype in a sandbox. After you approve it, the real build goes to an
-intworktree.Directorysuperlite/
Directory.claude/
Directoryworktrees/
Directorysessions-docs-site/ the docs session
- …
Directorysessions-people-you-may-know-int/ the feature’s integration build
- …
Directory.superlite/
Directorysandboxes/people-you-may-know/ the prototype, not a worktree
- …
Underneath, one feature gets one worktree. The prototype’s code is ported into it task by task.
What you end up with: the docs session and the “People you may know” feature each in their own folder and branch. When a session closes, session close removes the worktree superlite cut for it and keeps the branch for the pull request.
Good to know
Section titled “Good to know”session closeremoves a worktree superlite cut.ExitWorktreeonly leaves it.- A review of another branch uses
superlite-cli session ensure --branch <target>. - Merging at shipping never switches your main checkout when it hosts another open session. superlite merges in a temporary
merge-<base>worktree and removes it.
See how a session ends in Session lifecycle, or read the Feature flow.