Troubleshooting & releases
Platform Notes
Spruce runs on macOS, Windows, and Linux. Most features work identically across platforms, but a few behaviours differ; this page captures the differences.
- Application-data directory:
~/Library/Application Support/com.spruce.app/ - Daemon transport: Unix socket at
~/Library/Application Support/com.spruce.app/daemon.sock - Default shell:
/bin/zsh -lunless overridden in Global Preferences - Credentials: Keychain
- Gatekeeper: On first launch, macOS verifies the app is from a trusted developer. Right-click the app and pick Open if you hit a Gatekeeper block on downloads.
- Application-data directory:
%APPDATA%\com.spruce.app\ - Daemon transport: named pipe
- Default shell:
pwsh.exeif installed, otherwisepowershell.exe, otherwisecmd.exe - Credentials: Windows Credential Manager
Known Windows-specific behaviour
Path case sensitivity
Paths inside the Spruce project are case-insensitive in the filesystem but case-sensitive in Spruce's storage. Be consistent with capitalization when editing template files directly.
Terminal PTY differences
Terminal sessions use Windows ConPTY; a few niche tools that assume TTY quirks specific to macOS/Linux may behave differently. Pipe-based tools work normally.
Claude Code launch via actions
Launching Claude Code (or other agents) through a Spruce action on Windows can fail because the action's prompt body gets passed via a temp file, and Windows path / quoting handling for that temp file is finicky. We're actively working on a fix; in the meantime, agent-launch actions may need extra setup on Windows compared to macOS / Linux.
- Application-data directory:
$XDG_CONFIG_HOME/com.spruce.app/or~/.config/com.spruce.app/ - Daemon transport: Unix socket
- Default shell:
$SHELL, falling back to/bin/bash - Credentials: Secret Service / libsecret (GNOME Keyring, KWallet, etc.)
Linux known issues
Less battle-tested
Linux builds are less battle-tested than macOS and Windows. File issues for anything that doesn't work.
Wayland resize quirks
On Wayland, some terminal resize behaviour may need a window focus change to pick up correctly. Report if you hit this.
Installing spruce-cli on PATH
spruce-cli ships inside the Spruce app bundle:
- macOS:
/Applications/Spruce.app/Contents/MacOS/spruce-cli - Windows: installed alongside the main
.exe - Linux: in the
bin/directory of the AppImage /.deb/.tar.gz
Symlink or add to PATH per your preference. See Spruce CLI.
Related
- Install Spruce — initial install instructions per platform.
- Shell Configuration — picking a shell.
- Spruce CLI — CLI commands and the daemon.