Manage your sessions

Open persistent work

From a local checkout you have pushed to a Box:

schooner start

Schooner uses the remembered remote Worktree, creates a managed tmux session if needed, and attaches your terminal. If that Worktree already has a managed live session, start reuses it.

To detach with the standard tmux key binding, press Ctrl+B, release both keys, then press D. The session keeps running on the Box. Return later from the same local checkout:

schooner resume

resume only attaches to existing work; it never creates a session. If the session has ended, use start. The Box must remain running for its processes to stay alive. See resume your work for connection troubleshooting.

See what is running

From your local terminal:

schooner sessions

The list shows session IDs, names, ownership, Worktree association, and attached-client counts. Managed sessions were created and identified by Schooner. Unmanaged sessions are other live tmux sessions Schooner can observe. A session’s association describes whether its Worktree can still be matched to live Git state.

Inspection commands choose their own Box

sessions, logs, stop, and shell do not follow your checkout’s Local Link. On your workstation they use an explicit Box, your default, the sole configured Box, or a choice when needed. If you have several machines, add --box work-api to inspect the intended one. Replace work-api with its name.

Check recent output

schooner logs

If there is one managed session, Schooner selects it. If there are several, it asks you to choose. The default is the most recent 200 lines of captured pane output.

Capture more history from an exact session

Copy a managed ID from schooner sessions, then replace SESSION_ID:

schooner logs SESSION_ID --lines 500

The accepted range is 1–2,000 lines. Output is also bounded to 64 KiB, so large output may be truncated. This is a snapshot of available tmux pane history, not a continuous log stream or permanent log archive.

Stop work you have finished

schooner stop

Choose a managed session and confirm that it should stop. This ends the tmux session and its running work, while leaving the Worktree files in place. Use detach when you want processes to continue running.

Stop an exact session

schooner stop SESSION_ID

Replace SESSION_ID with a managed ID from the session list. An explicit ID stops that session without the interactive confirmation. stop and logs only accept managed sessions; a repository name or Worktree path is not a session ID.

Open a temporary shell

schooner shell

Schooner selects the only available Worktree or asks you to choose one. The shell opens in that directory without creating a persistent managed session. Exit normally when you are done.

To open a particular Worktree, use its path from schooner worktree list:

schooner shell repository-feature

start, resume, and shell need an interactive terminal and human output. They are terminal handoffs rather than commands for capturing JSON in a pipeline.

Select other persistent work

Use an exact Worktree path or session ID

schooner start repository-feature
schooner resume repository-feature

Replace repository-feature with an existing remote Worktree path. resume also accepts an exact session ID from the session list. Explicit selectors bypass the no-selector checkout-link path, so choose the Box explicitly too when your default is not the intended machine.

Without a Local Link, bare resume uses the current local repository as context; outside a local repository it selects the newest managed live session on the chosen Box. It does not create missing work. Command defaults explains routing in more detail.

---

Checked against the session commands, tmux implementation, and session lifecycle tests at 03d6623.