FAQ & Troubleshooting

Ctrl+Space does nothing (macOS)

macOS grabs Ctrl+Space for input-source switching. Either untick Select the previous input source in System Settings → Keyboard → Keyboard Shortcuts… → Input Sources, or just change the prefix: open Settings from the Menu button, go to Keys, and set the Prefix row to F12, Ctrl+b, or another supported key. The no-Ctrl (F12) preset avoids the macOS input-source shortcut entirely (on media-key keyboards, press Fn+F12). See Keybindings. Meanwhile: everything is mouse-driven, and Shift+↑ scroll mode needs no prefix.

I upgraded but see no changes

The background server is still the old version, and it keeps running across installs by design. Run luvus server restart (your session is saved and restored) for the selected session, or luvus server restart --all to restart every currently running session. Stopped sessions remain stopped. The named-session switcher also detects another running session left on the previous version and restarts that session before switching; direct attaches fail with the restart instruction instead of entering an incompatible client connection.

The git tab is empty / PRs are missing

Run luvus doctor. Local views need git. PRs/issues need an authenticated gh (gh auth login). Without gh the tab is a local-git viewer.

An agent shows as plain zsh / isn’t detected

luvus identifies an agent by the program running in the pane, matched against a list of names it knows (Claude Code, Copilot, Codex, opencode, Kimi, Cursor, Gemini, Aider, Amp, Droid, Grok, Hermes, Letta Code, Muse, Qwen, Kilo Code, Kiro, Devin). If your agent runs under a name luvus does not know, teach it one in ~/.luvus/manifests/<agent>.toml:

agent = "myagent"

[identity]
distinct = ["myagent-cli"]

See Custom detection rules for the full format. If you would like it built in, open an issue.

A pane is detected as the wrong agent

This should not happen any more. luvus used to read agent names off the pane’s screen, so a pane that merely printed “amp” or “cursor” was mistaken for that agent. Identity now comes from the running process instead. If you still see it, please open an issue with what the pane was running.

Where can I find runtime diagnostics?

Luvus keeps private structured diagnostics in the selected session directory at the info level by default. The default session writes ~/.luvus/logs/server.log and ~/.luvus/logs/client.log. Read recent records with ordinary tools such as tail -n 200 ~/.luvus/logs/server.log. Named sessions keep the same files under ~/.luvus/sessions/<name>/logs/. Set LUVUS_LOG=off before starting a process only when you need to disable logging.

Logs never include pane output, prompts, keystrokes, file contents, command arguments, or UHP request bodies. They can still describe your local runtime, so review them before attaching them to a public issue.

Where did my scrollback go?

Each pane has a 10 MiB retained-history budget by default, adjustable in Settings → Layout → Scrollback memory. Luvus’s current terminal engine translates that into a conservative row limit, so the displayed usage is an estimate rather than an exact allocation count. Full-screen apps (vim, TUI agents) own their own scrolling, and luvus forwards the wheel to them, so use the app’s native scrolling there.

Windows: what’s different?

Use Windows Terminal. Live per-pane cwd tracking and the shell hook aren’t available, and luvus cannot inspect a pane’s processes, so it identifies agents from the command, window title, and screen text instead. Zero-config agent resume still works. Named pipes replace Unix sockets transparently.

The terminal shows “◱ enlarge terminal”

The window is too small to render the UI (under ~24×6 cells). Make it bigger.

How do I completely reset?

luvus server stop
rm -rf ~/.luvus        # session, config, orch ledger, modules: everything