Agent Empire

Your projects are planets. Your coding agents are ships. You run the galaxy.

Give Claude, Codex or Grok a task, open a terminal beside it, and move on to another world. Empire keeps the sessions alive and shows you who is working, who needs an answer, and what is ready to review. Come back to the same fleet when you reopen your terminal.

A real render with fictional projects. Planets, ships, nebulae and sound are generated in code.

User guide · Get started · Daily workflow · Controls · Full manual · Contributing

A place for the work you have in flight

• One map for many projects. Folders become worlds, parent folders become systems, and Git worktrees orbit their projects as stations.
• Your agents, in their native terminals. Launch installed coding CLIs and keep their normal tools and permission prompts. Ordinary shells live alongside them for servers, tests and Git.
• Tasks that wait their turn. Queue a prompt for a project's next available agent, or launch a new ship. Jump to the next agent that needs your attention.
• A workspace that stays put. Close the galaxy without stopping your agents or development servers. Reopen it to reconnect.
• Progress you can see. Git changes, pull requests, project findings and agent resources have a place on the map. Procedural worlds and an ambient soundtrack make it feel like somewhere.

Get started

Empire runs on Linux with Git and a true-color terminal. A font with Unicode 16 octant glyphs gives the intended graphics. Install and authenticate your coding agents separately.

Download a ready-to-run build

GitHub Releases provide x86-64 and ARM64 binaries. No Rust toolchain or compiler is needed. They require glibc 2.35+ (Ubuntu 22.04+ or a recent compatible distribution) and the ALSA runtime library, even when sound is muted. Install libasound2 on Ubuntu 22.04, libasound2t64 on Ubuntu 24.04, or alsa-lib on Arch.

Download the installer, then run it:

curl -fL https://github.com/Cozidian/agent-empire/releases/latest/download/install.sh -o /tmp/empire-install.sh
bash /tmp/empire-install.sh
~/.local/bin/empire --version
~/.local/bin/empire

The installer selects your architecture, verifies the archive's SHA-256 checksum and installs into ~/.local/bin. It also keeps license notices beside the command as empire.LICENSE, empire.THIRD-PARTY-NOTICES.txt and empire.RUST-THIRD-PARTY-NOTICES.html. Add that directory to PATH to use empire from any terminal. Use --version v0.1.0 for a specific release or --bin-dir /your/bin for another location. Run it again to update; it replaces the command without stopping your agents. empire upgrade switches a running daemon to the installed build—it does not download updates.

For manual installation, verify the matching archive against SHA256SUMS, extract it and copy empire into a directory on your PATH. Removing that binary uninstalls the command; it leaves your local state intact. Alpine/musl, macOS and Windows binaries are not currently provided.

Build from source

You need a recent stable Rust toolchain, a C toolchain, pkg-config and ALSA development headers. On Debian/Ubuntu: sudo apt install build-essential pkg-config libasound2-dev git. On Arch: sudo pacman -S --needed base-devel alsa-lib git.

Install and authenticate at least one supported agent CLI (claude, codex or grok) separately. Empire uses the executables on your PATH; it does not include model access or an AI subscription. The GitHub station additionally uses an authenticated gh CLI. You can explore projects and use ordinary terminals without an agent installed.

git clone https://github.com/Cozidian/agent-empire.git
cd agent-empire
cargo build --release --locked
./target/release/empire

To launch with empire from any terminal, link the release build into your user command directory (which must be on your PATH). Run this from the repository root after building:

mkdir -p ~/.local/bin
ln -s "$PWD/target/release/empire" ~/.local/bin/empire
empire

The link uses this checkout's release build, so cargo build --release updates the command too. Keep the checkout in place while using the link.

Your first flight

1. Press V, then n, to add a folder containing your projects. Empire discovers repositories beneath it. Use n on the galaxy to add just one folder instead.
2. Select a planet and press Enter. Press t to give it a task or e to launch an agent.
3. Open the agent's native terminal to talk to it. F12 or Ctrl-] returns to Empire.
4. Press b in the project to open a shell and run your tests or development server.
5. Press q from the galaxy when you're done looking around. Your sessions keep running.

New here? Press ? on the galaxy for help. Closing the UI keeps sessions alive; empire stop deliberately stops the daemon and every session.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗