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 another chord such as Ctrl+b (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). luvus also warns about this at attach.

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, Qwen, Kiro). 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 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