Settings
Shell Configuration
Spruce's terminal sessions launch using a configurable shell. By default Spruce picks a sensible shell per platform, but you can override it; useful if you've migrated to fish, zsh, nu, or a custom login profile.
Global setting
Open Settings → Global preferences → Terminal. Fields:
- Shell command: the binary to launch (e.g.
/bin/zsh,/usr/local/bin/fish,pwsh.exe). - Shell arguments: arguments passed on launch (typically to source a profile, e.g.
-lfor a login shell).
Changes apply to newly opened sessions. Existing sessions keep running under their previous shell.
Platform defaults
| Platform | Default shell |
|---|---|
| macOS | /bin/zsh -l |
| Linux | $SHELL if set, otherwise /bin/bash |
| Windows | pwsh.exe (PowerShell 7) if available, else powershell.exe, else cmd.exe |
See Platform Notes for platform-specific quirks around PTY behaviour.
Working directory
When a session opens on an artifact, Spruce sets the cwd to the artifact's worktree (if the artifact has been Start Working'd) or to the first linked code repo's root (or the project's resources/ folder for plan-only projects). You can cd anywhere you want once the session is running.
Environment variables
Any variables set in your shell's profile (e.g. .zshrc, .bashrc) apply, because Spruce launches the shell the way your terminal emulator would. For Spruce-specific variables, set them in the profile just like you would for any other tool.
Native terminal app
Beyond the shell that powers Spruce's embedded sessions, you can pick a native terminal app Spruce uses for two flows:
- Open in native terminal: the icon on each session that launches your usual terminal app already attached to the session's PTY. Useful when you want full muscle memory (copy/paste shortcuts, scrollback search, your own theme).
spruce-cli session open-in-terminal: the CLI subcommand (and the Open in native terminal icon's underlying call) spawns a new tab/window in your preferred terminal and attaches the session there. This setting controls the fallback when there's no other signal to pick a terminal from. See Spruce CLI → Sessions.
Set this under Settings → Global preferences → Native terminal app. Spruce detects which launchers are installed on your system and offers them in a dropdown. Typical options:
- macOS: Terminal.app, iTerm2, Ghostty, Warp, Alacritty.
- Linux: GNOME Terminal, Konsole, Ghostty, Alacritty, Kitty.
- Windows: Windows Terminal, WezTerm.
If your preferred terminal isn't detected, leave it on the auto-pick default and Spruce will fall back to the OS's standard terminal.
See Sessions → Opening in your native terminal for the per-session UI.
Related
- Sessions — the sessions that use this shell.
- Platform Notes — platform-specific terminal behaviour.
- Global Preferences — the wider Settings page.