09 / Reference

Sessions, updates & privacy

The galaxy is a window into your sessions. The daemon keeps them alive.

What keeps running

Pressing q on the galaxy, or closing its window, leaves the daemon, agents and ordinary shell commands running. Reopening Empire reconnects to them.

After a reboot or daemon crash, supported agents resume their recorded conversations. Ordinary shells reopen in their original project folders, but commands and development servers must be started again.

Stopping is different from leaving. empire stop closes the daemon and every session, and clears the resume registry. Use it only when you intend to recall the whole fleet.

Update Empire

After updating the checkout, build the release binary:

cargo build --release --locked

Close and reopen only the galaxy. It can hot-upgrade the daemon in place while keeping agent PTYs. A symlink to the release binary continues to use this checkout's new build.

For an explicit daemon upgrade, run empire upgrade. If a build reports an upgrade problem, inspect the message and daemon log before taking a disruptive action. Do not use empire stop as a routine update step.

Useful commands

empire status          # one-line fleet summary
empire status --json   # Waybar-compatible JSON
empire upgrade         # hot-upgrade the daemon
empire sounds          # preview sound cues
empire graphics        # offline graphics comparison
empire research        # standalone Research Station

In the galaxy, lowercase m mutes alert cues and uppercase M mutes music. These controls are independent. Music stops when you leave the UI.

Where data lives

Location	Contents
`$XDG_STATE_HOME/empire`	Workspace settings, session registry, tasks, findings, screenshots, progress and history
`$XDG_STATE_HOME/empire/research`	Study snapshots, trial workspaces, reports, proposed patches and model traces
`$XDG_DATA_HOME/empire/research`	Optional research runtime and Python environment

The usual defaults are ~/.local/state for state and ~/.local/share for data. Agent CLIs also maintain their own histories outside Empire.

Privacy and trust

Empire is a local controller for your Linux account. Both ends of a daemon connection check the peer's user ID. The socket uses mode 0600; the daemon creates or tightens its state directory to 0700. Logs, handoffs and registry writes are private to the user.

Processes running as you are inside the trust boundary. Empire does not sandbox them or replace agent permissions. Do not expose its socket through a network proxy or share a Unix account with someone who should not control your fleet.

Saved tasks, screenshots and model traces can contain confidential source or pasted credentials. Native CLIs contact their configured model providers. Review saved data before sharing it, including screenshots used in bug reports.

See the repository's security policy for reporting a vulnerability.

Agent integration files

Claude launches receive Empire hooks and a status-line command through their launch settings. Empire does not rewrite your Claude settings file. Its status-line bridge forwards input to your configured command from $CLAUDE_CONFIG_DIR/settings.json (default ~/.claude/settings.json), running it through sh -c.

Grok integration writes $GROK_HOME/hooks/empire.json (default ~/.grok/hooks/empire.json) without modifying other hook files. It contains the Empire executable path and hook configuration, not mission transcripts. The hooks do nothing for sessions Empire did not launch.