Troubleshooting

On Linux and macOS, the server writes logs to ~/.local/state/ship/logs/default/ (under $XDG_STATE_HOME if you set it, and a named server uses its name in place of default). To follow along:

tail -F ~/.local/state/ship/logs/default/current.log

Client windows write to ~/.local/state/ship/logs/client/. On Windows, these folders are under Ship's platform data directory instead. Problems that don't show up on screen end up in one of these, so a saved directory that disappeared is in the server log and a sound file that wouldn't load is in the client log. Ship cleans up old logs on its own.

Logs don't record pane input or output, but programs started by run actions write their output here. Error messages can also include program names and paths, so check a log before you share it.

Turn up the server's logging without restarting it, and put it back when you're done:

ship server log debug
ship server log --reset

To start a server or window with more logging, set SHIP_LOG:

SHIP_LOG=debug ship

If a program renders wrong in a pane, the server log has Ghostty's warnings about terminal features it doesn't support, which helps you tell a missing terminal feature from a Ship bug.

For something that feels slow, record a timeline and open it in Perfetto:

SHIP_TRACE=/tmp/ship-trace ship server --name trace --starter
SHIP_TRACE=/tmp/ship-trace ship --server-name trace   # another terminal

Do the slow thing, detach with alt-q, then stop that server with ship --server-name trace server stop. The timelines are in /tmp/ship-trace/ and aren't size-limited, so keep recordings short.