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 artu server restart (your session is saved and restored). artuditu also warns about this at attach.

The git tab is empty / PRs are missing

Run artu 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

artuditu 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 artuditu does not know, teach it one in ~/.artuditu/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. artuditu 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?

Artuditu keeps private structured diagnostics in the selected session directory. The default session writes ~/.artuditu/logs/server.log and ~/.artuditu/logs/client.log. Read recent records with ordinary tools such as tail -n 200 ~/.artuditu/logs/server.log. Named sessions keep the same files under ~/.artuditu/sessions/<name>/logs/.

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. Artuditu’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 artuditu 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 artuditu 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?

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