10 / Reference

Troubleshooting

Start with the smallest check that explains the symptom.

The build cannot find ALSA or pkg-config

Install the native packages listed in the setup guide. On Debian/Ubuntu the ALSA development package is libasound2-dev; on Arch it is alsa-lib. Use a recent stable Rust toolchain, then rerun cargo build --release --locked.

My agent is missing or cannot authenticate

Run its command in the same terminal environment you use to launch Empire. Confirm it is installed on PATH and complete its native login flow. Empire does not install agent CLIs or supply provider credentials. Reopen the UI after installing a CLI.

My project does not appear

Use V to check configured roots. A root discovers repositories beneath it, but does not descend inside another repository, follow symlink directories or search hidden directories. Add an unusual folder directly with n on the galaxy.

Press uppercase R on Home to rescan. If you previously removed a project from the map, add its folder again to restore it. Removing a root does not delete project files.

A worktree or its agent has not moved

Check git worktree list in the main project. Empire surveys the registry about every eight seconds while the galaxy is open. The checkout must exist and must not be explicitly hidden.

Seeing a station and moving a ship are separate observations. The ship follows recorded command working directories or native hook reports. Ask it to execute in the worktree; merely mentioning the path, using git -C, or changing directories inside a shell may not report a new native directory. Older Codex logs may lack the necessary records.

Shift+Enter submits, or Escape does not leave

In a native agent terminal, the terminal emulator must distinguish Shift+Enter, and the agent must support it as a newline shortcut. Reopen Empire after updating it. If the terminal cannot report it separately, try the agent's Alt+Enter or Ctrl+J binding.

In Empire's task composer, all three bindings insert a newline. Esc cancels that composer. Inside a native terminal, Esc goes to the agent; F12 or Ctrl+] returns to Empire.

Graphics look broken, or there is no sound

Use a true-color terminal and a font with Unicode 16 octant glyphs. Missing glyphs can appear as empty boxes. Run empire graphics for an offline comparison; Space switches renderers, p pauses rotation and q leaves.

In the galaxy, check the separate m alert and M music toggles. empire sounds previews cues and reports when no audio device is available.

GitHub signals are missing or stale

Run gh auth status and verify that the project has a GitHub remote. A ? marker means unavailable or cached data. The normal refresh interval is 150 seconds, and data older than 7½ minutes is marked stale. Passing CI alone does not remove a PR from the list.

The daemon is offline or cannot start

Run empire status and inspect ~/.local/state/empire/daemon.log, or the equivalent under your XDG_STATE_HOME. Check that your state directory belongs to your user and is not a symlink.

If you set EMPIRE_SOCK, check its parent directory and use the same value in every command. Empire refuses to replace another user's socket or a regular file at the socket path. Investigate the path instead of deleting an unfamiliar file.

Report a reproducible bug

Include your Empire commit, Linux distribution, terminal and font, the affected agent CLI version, the steps taken, and expected versus actual behavior. Use a fictional project or redact private paths and prompts in screenshots.

For a public bug, use GitHub issues. For security problems, follow SECURITY.md instead of posting exploit details.