Skip to main content
Spruce

Spruce

Docs

Discord

Tools

Sessions

A session is one of Spruce's built-in terminals. Sessions are scoped per artifact (and its worktree), so the commands you run stay isolated to the piece of work at hand. They show up in two places, both labelled Sessions in the UI:

  • The global Sessions page (in the Tools section of the sidebar): a session list on the left, active terminal on the right. Use it when you want a project-wide view of what's running across artifacts.
  • The Sessions tab in the tool panel: when you have an artifact open, this tab strips the list down to a row of tabs across the top of the panel (the artifact already scopes the list, so a list view would only ever contain its own sessions).

The two surfaces share the same backing sessions. Open one in either, and it shows up in the other.

The global Sessions page (left) and the per-artifact Sessions tab (right)The global Sessions page (left) and the per-artifact Sessions tab (right)

Opening a session

From either surface:

  • Global Sessions page: click + New session at the top of the session list. Picks the active artifact's worktree as the working directory, or a sensible default if no artifact is in scope.
  • Per-artifact Sessions tab: click + in the tab strip. The new tab opens with the working directory set to the artifact's worktree.

You can also use the keyboard shortcut. See Keyboard Shortcuts.

Many sessions per artifact

You can create as many sessions as you need for a single artifact: one running the dev server, another running tests in watch mode, another for ad-hoc commands. Rename, kill, and reorder from the tab's right-click menu.

The Sessions tab in the tool panel shows a colored play-icon badge when sessions exist for the open artifact: teal when running, orange-pulse when a session is awaiting input. The session count is appended after the label.

Running actions

Click the + dropdown to run a project-defined action (dev server, test suite, launch Claude). Actions open a new session with a pre-filled command. See Actions and Action Recipes.

Persistence

Sessions are managed by the Spruce daemon. The daemon holds each session's PTY (pseudo-terminal) and state, so sessions survive:

  • Switching between artifacts. The session stays running in the background.
  • Switching between projects. Sessions tied to the prior project continue.
  • Resizing the terminal panel. The PTY reflows.
  • Switching between the global Sessions page and the per-artifact Sessions tab. Same session, different housing.

Sessions don't survive quitting Spruce; the daemon shuts down with the app.

Opening in your native terminal

The embedded session panel works for most flows, but sometimes you want the full muscle memory of your usual terminal — copy/paste shortcuts, scrollback search, your own theme. Click the Open in native terminal icon (top of the active-session view, or in a session-tab's right-click menu) and Spruce launches your configured native terminal app already attached to that session's PTY.

Spruce supports a list of native launchers (Terminal.app, iTerm2, Ghostty, GNOME Terminal, Konsole, Windows Terminal, etc.) and detects which ones are installed. Pick your default under Settings → Global Preferences → Native terminal app. See Global Preferences.

The session keeps running in the embedded panel even after you open it in your native terminal: both surfaces stay attached to the same PTY. Closing the native terminal window detaches it without killing the session.

Reaching sessions from outside Spruce

Sessions are managed by the Spruce daemon, so they're reachable from any shell, not just inside Spruce. The CLI's session subcommands cover listing, attaching, killing, and opening in your native terminal. See Spruce CLI → Sessions for the full reference.

Shell configuration

Your shell, arguments, and working-directory policy are configurable. See Shell Configuration.

Tools

Comments

Tools

Git