Worktree sessions under a channel #51

Merged
pedromcaraujo merged 3 commits from worktree-sessions into main 2026-10-31 12:13:38 +00:00

Closes #50. Groundwork for #40.

Run more than one Claude session per project, each on its own git worktree and branch, without a NixOS rebuild.

What changes

  • Palette → Create worktree asks for a name (name, or name@base to branch from something other than HEAD). Forge then creates the worktree and branch, starts a session in it, and switches to it.
  • Sidebar: worktree sessions are indented under their channel, each with its own status dot and a × to close it. On a phone they follow their channel's pill. They share the channel's issues drawer and upload dir.
  • Close: the session is killed and the worktree removed if it's clean. If it has uncommitted changes, Forge asks before forcing. The branch is always kept.
  • Discovery: any linked worktree of the repo is listed, including ones made by claude --worktree. Clicking a stopped one (e.g. after a reboot) restarts its session.

How

  • A worktree session is the tmux session <channel>~<name>.
  • It's served by the channel's existing ttyd with --url-arg (/<channel>/?arg=<name>). The launcher script accepts only a plain name and only attaches to an existing session, so a crafted URL can't start a session in the wrong place.
  • The forge-tmux sidecar owns /worktrees (list/create/open/close) and starts sessions with the same session script ttyd uses, now factored out.
  • New options: worktreeDir (default .claude/worktrees, relative to the channel cwd and added to the repo's local .git/info/exclude) and a per-channel worktrees toggle.

Fixes along the way

  • tmux targets are now exact (=name:). A bare -t forge prefix-matches forge~x when the channel's own session is down.
  • forge-tmux gets KillMode=process: it can now be the process that spawns the shared tmux server, so a redeploy must not kill it.

Tested

  • Sidecar endpoints, against a scratch repo and a private tmux server: create, list, status, keys, dirty close (409), forced close, reopen, reusing an existing branch, name@base, a worktree made outside Forge, and invalid names/base refs.
  • Launcher script with hostile ?arg= values ($(...), ../x, two args): all refused, nothing runs.
  • Builds: the flake eval check passes and the launcher JS parses.
  • Not yet tried in a browser: needs a deploy.
Closes #50. Groundwork for #40. Run more than one Claude session per project, each on its own git worktree and branch, without a NixOS rebuild. ## What changes - **Palette → Create worktree** asks for a name (`name`, or `name@base` to branch from something other than HEAD). Forge then creates the worktree and branch, starts a session in it, and switches to it. - **Sidebar:** worktree sessions are indented under their channel, each with its own status dot and a `×` to close it. On a phone they follow their channel's pill. They share the channel's issues drawer and upload dir. - **Close:** the session is killed and the worktree removed if it's clean. If it has uncommitted changes, Forge asks before forcing. The branch is always kept. - **Discovery:** any linked worktree of the repo is listed, including ones made by `claude --worktree`. Clicking a stopped one (e.g. after a reboot) restarts its session. ## How - A worktree session is the tmux session `<channel>~<name>`. - It's served by the channel's existing ttyd with `--url-arg` (`/<channel>/?arg=<name>`). The launcher script accepts only a plain name and only attaches to an existing session, so a crafted URL can't start a session in the wrong place. - The forge-tmux sidecar owns `/worktrees` (list/create/open/close) and starts sessions with the same session script ttyd uses, now factored out. - New options: `worktreeDir` (default `.claude/worktrees`, relative to the channel cwd and added to the repo's local `.git/info/exclude`) and a per-channel `worktrees` toggle. ## Fixes along the way - tmux targets are now exact (`=name:`). A bare `-t forge` prefix-matches `forge~x` when the channel's own session is down. - forge-tmux gets `KillMode=process`: it can now be the process that spawns the shared tmux server, so a redeploy must not kill it. ## Tested - **Sidecar endpoints**, against a scratch repo and a private tmux server: create, list, status, keys, dirty close (409), forced close, reopen, reusing an existing branch, `name@base`, a worktree made outside Forge, and invalid names/base refs. - **Launcher script** with hostile `?arg=` values (`$(...)`, `../x`, two args): all refused, nothing runs. - **Builds:** the flake eval check passes and the launcher JS parses. - **Not yet tried in a browser:** needs a deploy.
Add worktree sessions under a channel (#50)
All checks were successful
CI / check (pull_request) Successful in 40s
fefe658f09
A channel can now run extra Claude sessions, each on its own git worktree,
listed indented under the channel in the sidebar and created from the
palette ("Create worktree"). No rebuild per session: a worktree session is
the tmux session `<channel>~<name>`, served by the channel's existing ttyd
via `--url-arg` (`/<channel>/?arg=<name>`).

- forge-tmux sidecar: /worktrees list/create/open/close. Close removes the
  worktree only when clean (409 + confirm otherwise); the branch is kept.
- New `worktreeDir` option (default `.claude/worktrees`, relative to the
  channel cwd) and per-channel `worktrees` toggle.
- tmux targets are now exact (`=name:`); a bare `-t forge` prefix-matched
  `forge~x` when the channel's own session was down.
- Session command factored into one script shared by ttyd and the sidecar.
- forge-tmux gets KillMode=process, since it may now spawn the tmux server.

Closes #50
Replace the sidebar tmux cheat sheet with a prefix+? popup
All checks were successful
CI / check (pull_request) Successful in 10s
f6f3b9fca2
The cheat sheet permanently took sidebar space that worktree sessions now
need. prefix ? (normally tmux's raw list-keys dump) opens a curated sheet
in a popup instead, covering tmux and the launcher's own shortcuts; the
full table stays reachable as `prefix : list-keys`. The sidebar hint
points at it.
Palette: lead with the channel's worktrees, worktree actions last
All checks were successful
CI / check (pull_request) Successful in 10s
e6ffd71c62
With no input the palette opens on the current channel's sessions (its
worktrees, plus the channel itself from inside a worktree), then actions
and channels. Create/Close worktree always sort last, so they are never
the row Enter picks by default.
pedromcaraujo deleted branch worktree-sessions 2026-10-31 12:13:38 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
pedromcaraujo/forge!51
No description provided.