iw start puts the worktree session on the caller's tmux server, with no way to choose another #685

New issue

Closed

opened 2026-10-02 11:13:58 +00:00 by claude · 3 comments

claude commented

2026-10-02 11:13:58 +00:00

Member

What happens

iw start run from inside a tmux session creates the worktree's session on that same tmux server — the one named by $TMUX. As a default this is reasonable: a person in tmux gets the new session next to the ones they already have.

There is no way to choose another server, and that hurts when the caller's server belongs to something with its own lifecycle.

Where it bit us (procedures, dev machine, 2026-10-02)

Claude Code Remote Control runs as a systemd user unit, claude-rc-home.service, which starts tmux -L claude-rc new-session -d -s rc-home … and stops with tmux -L claude-rc kill-server.
A Remote Control session ran ./iw start shared-base and ./iw start email-port. Both worktree sessions landed on the claude-rc server.
A later systemctl --user restart claude-rc-home killed that server, and with it both worktree sessions and the agents running in them. They had nothing to do with the unit.

A separate socket on its own does not fix this. A tmux server started from inside the unit sits in the unit's cgroup, so stopping the unit kills it anyway. Moving it out of the unit's lifetime takes something like systemd-run --user --scope.

Ask

Keep the current default. Add an override for which tmux server iw start / iw open use, for example:

a config key (per project, or user-wide), and/or an environment variable such as IW_TMUX_SOCKET, passed through as tmux -L <name> (or -S <path>);
possibly a way to start that server outside the caller's cgroup — or at least documentation that the caller needs to do so.

iw open and the dashboard must find a session on whichever server it was created on.

#572 — iw start on a tmux server that already runs gives the pane that server's IW_* values. Same root: the session is put on the caller's server.

## What happens `iw start` run from inside a tmux session creates the worktree's session on that same tmux server — the one named by `$TMUX`. As a default this is reasonable: a person in tmux gets the new session next to the ones they already have. There is no way to choose another server, and that hurts when the caller's server belongs to something with its own lifecycle. ## Where it bit us (procedures, dev machine, 2026-10-02) - Claude Code Remote Control runs as a systemd user unit, `claude-rc-home.service`, which starts `tmux -L claude-rc new-session -d -s rc-home …` and stops with `tmux -L claude-rc kill-server`. - A Remote Control session ran `./iw start shared-base` and `./iw start email-port`. Both worktree sessions landed on the `claude-rc` server. - A later `systemctl --user restart claude-rc-home` killed that server, and with it both worktree sessions and the agents running in them. They had nothing to do with the unit. A separate socket on its own does not fix this. A tmux server started from inside the unit sits in the unit's cgroup, so stopping the unit kills it anyway. Moving it out of the unit's lifetime takes something like `systemd-run --user --scope`. ## Ask Keep the current default. Add an override for which tmux server `iw start` / `iw open` use, for example: - a config key (per project, or user-wide), and/or an environment variable such as `IW_TMUX_SOCKET`, passed through as `tmux -L <name>` (or `-S <path>`); - possibly a way to start that server outside the caller's cgroup — or at least documentation that the caller needs to do so. `iw open` and the dashboard must find a session on whichever server it was created on. ## Related - #572 — `iw start` on a tmux server that already runs gives the pane that server's `IW_*` values. Same root: the session is put on the caller's server.

claude commented

2026-10-02 23:30:00 +00:00

Author

Member

Intake: needs-input

iw-cli already has an IW_TMUX_SOCKET environment variable. When it is set, every tmux call that iw start and iw open make gets -L <name>, and that overrides the server named by $TMUX (core/adapters/Tmux.scala:27-36, core/model/Constants.scala:17, docs/api/Tmux.md:26; since commit 73db21ed). So the scope of this issue is not clear yet.

Given that IW_TMUX_SOCKET exists, what must this issue add? (a) Only user documentation of IW_TMUX_SOCKET for this case (for example, set it in the Remote Control unit or the shell). (b) A config key as well as the variable. (c) Something else — please say what.
If you choose a config key, where does it go, and which wins when both are set? (a) Per project, in .iw/config.conf. (b) User-wide, in a file in the user's home. (c) Both. Also say the order: environment variable over config, or config over environment variable.
A tmux server that iw starts from inside a systemd unit stays in that unit's cgroup. Should iw do something about this? (a) Documentation only: the caller starts the server outside the unit, for example systemd-run --user --scope tmux -L <name> start-server. (b) iw starts the server itself with systemd-run --user --scope when the server is not running and systemd is present. (c) Out of scope for this issue.
The issue says "iw open and the dashboard must find a session on whichever server it was created on." At the moment each iw process and the dashboard look only at the server their own environment names. Which behaviour is required? (a) Same setting: whoever runs iw open or the dashboard must have the same IW_TMUX_SOCKET or config (a config key from question 2 makes this automatic). (b) iw records the server for each worktree when it creates the session, and iw open and the dashboard use that recorded server, whatever their own environment says.

Answer in a comment on this issue; intake reads it on its next iteration.

Intake: needs-input iw-cli already has an `IW_TMUX_SOCKET` environment variable. When it is set, every tmux call that `iw start` and `iw open` make gets `-L <name>`, and that overrides the server named by `$TMUX` (core/adapters/Tmux.scala:27-36, core/model/Constants.scala:17, docs/api/Tmux.md:26; since commit 73db21ed). So the scope of this issue is not clear yet. 1. Given that `IW_TMUX_SOCKET` exists, what must this issue add? (a) Only user documentation of `IW_TMUX_SOCKET` for this case (for example, set it in the Remote Control unit or the shell). (b) A config key as well as the variable. (c) Something else — please say what. 2. If you choose a config key, where does it go, and which wins when both are set? (a) Per project, in `.iw/config.conf`. (b) User-wide, in a file in the user's home. (c) Both. Also say the order: environment variable over config, or config over environment variable. 3. A tmux server that iw starts from inside a systemd unit stays in that unit's cgroup. Should iw do something about this? (a) Documentation only: the caller starts the server outside the unit, for example `systemd-run --user --scope tmux -L <name> start-server`. (b) iw starts the server itself with `systemd-run --user --scope` when the server is not running and systemd is present. (c) Out of scope for this issue. 4. The issue says "`iw open` and the dashboard must find a session on whichever server it was created on." At the moment each `iw` process and the dashboard look only at the server their own environment names. Which behaviour is required? (a) Same setting: whoever runs `iw open` or the dashboard must have the same `IW_TMUX_SOCKET` or config (a config key from question 2 makes this automatic). (b) iw records the server for each worktree when it creates the session, and `iw open` and the dashboard use that recorded server, whatever their own environment says. Answer in a comment on this issue; intake reads it on its next iteration.

claude added the

needs-input

label

2026-10-02 23:30:00 +00:00

mph commented

2026-10-10 19:19:21 +00:00

Owner

Close the issue and remove the label. We can redefine the env var if needed, the premise is wrong.

claude removed the

needs-input

label

2026-10-10 20:10:29 +00:00

claude commented

2026-10-10 20:11:23 +00:00

Author

Member

Intake: fixed by 73db21ed4e

The override this issue asks for exists: with IW_TMUX_SOCKET set, every tmux call of iw start and iw open gets -L <name> in place of the caller's $TMUX server (core/model/Constants.scala:17, core/adapters/Tmux.scala:27-36). The answer on this issue says the premise is wrong and asks to close it; the variable can be redefined in a new issue if needed.

Intake: fixed by 73db21ed4e86bc37457cd92865e090fb47036e1a The override this issue asks for exists: with `IW_TMUX_SOCKET` set, every tmux call of `iw start` and `iw open` gets `-L <name>` in place of the caller's `$TMUX` server (`core/model/Constants.scala:17`, `core/adapters/Tmux.scala:27-36`). The answer on this issue says the premise is wrong and asks to close it; the variable can be redefined in a new issue if needed.

claude closed this issue

2026-10-10 20:11:23 +00:00