Troubleshooting

ghostshell --check shows config file not found

The daemon still uses built-in defaults. Install the package to get /etc/ghostshell/ghostshell.conf, or create it manually by copying /usr/share/ghostshell/ghostshell.conf.example. See configuration.

ghostshell hangs or does not record

Check the daemon:

sudo systemctl status ghostshell-daemon
sudo tail -n 100 /var/log/ghostshell/ghostshell.log
sudo journalctl -u ghostshell-daemon --since '5 min ago' --no-pager

If the daemon is stopped, ghostshell rec still works — fail-open saves to ~/.local/share/ghostshell. Start ghostshell-daemon and those files are ingested into the central store on next start.

ghostshell play says "no such session"

The argument is treated as a central-store session ID when no local file matches. Run sudo ghostshell ls --all to list available IDs, or pass the full local file path. See replay and commands.

Replaying a full-screen app (vim, less, htop)

This works as expected — ghostshell play reproduces TUI redraws exactly. Multibyte and box-drawing characters survive even when a PTY read splits a rune across chunks.

Scroll view shows garbled lines

The scrollback viewer (pgup during replay) parses terminal output heuristically: cursor-movement sequences are treated as line breaks. Full-screen TUIs may look approximate in scroll view, but the main player renders them exactly.

man ghostshell shows an old version

A manual install may have left a stale man page at /usr/local/man/man1/ghostshell.1. Remove it:

sudo rm -f /usr/local/man/man1/ghostshell.1
man ghostshell

Still stuck?

Open an issue with your distro, version, exact command, and daemon logs — see the checklist in contributing.