Ilium

Running 100+ CLI agents across dozens of projects and need some help auto-organizing that mess?
Keep agent work, terminals, editors, and boards together, with activity in view.

_{Linux · macOS · Windows · Rust · MIT}

Quick start · Daily use · Demos · Features · Full documentation

This README is the short version. The full documentation has the step-by-step guides, every setting, key and command.

Quick start

Linux preview: v0.1.1-linux.3 provides Linux x86_64 (six formats) and Linux ARM64 (four formats) from one source commit, with one SHA256SUMS covering all ten files. The public downloads have been checked against their checksums. This prerelease is not marked as latest; the full cross-platform v0.1.1 release remains pending.

Not yet available for this preview: two of six Linux ARM64 formats (rpm, Snap), macOS Intel and Windows. The macOS Apple Silicon packages are unsigned and not notarized, so Gatekeeper warns: right-click and choose Open, or run xattr -dr com.apple.quarantine <file>. Plugins are an unsupported development preview.

Plugin code is present for future integration and is not yet available for use.

Install the Linux x86_64 preview (no root required):

curl --proto '=https' --tlsv1.2 -LsSf https://ilium-setup.pages.dev/install.sh | sh

The Linux installer supports x86_64 and ARM64 (aarch64); ARM64 has been verified in an emulated guest only.

Windows PowerShell (coming soon: the Windows package is not yet available):

irm https://ilium-setup.pages.dev/install.ps1 | iex

Windows downloads are not yet available: per-user setup .exe, .msi, and ZIP.

Direct downloads (Linux x86_64 preview; other systems not yet available):

System	Downloads / availability
Linux x86_64 (6 of 6 available and verified)	tar.gz · deb · rpm · AppImage · Snap · Flatpak
Linux ARM64 (4 of 6 available and verified; emulated QEMU, not native hardware)	tar.gz · deb · AppImage · rpm (coming soon: only a limited --nodeps install was tested) · Snap (coming soon: install not verified) · Flatpak
macOS Apple Silicon (4 of 4 available and verified; native macOS build, tests and installed-package checks; unsigned, not notarized; animations disabled)	tar.gz · ZIP · PKG · DMG
macOS Intel	tar.gz, ZIP, PKG, DMG (coming soon; not yet available)
Windows x86_64	setup .exe, MSI, ZIP (coming soon; not yet available)

Linux ARM64: 4 of 6 ARM64 formats available and verified. The tar.gz, deb, AppImage and Flatpak ran in an emulated ARM64 (QEMU) guest; no native ARM64 hardware has been tested. Both architectures are in the same prerelease, v0.1.1-linux.3.

Verify every package using SHA256SUMS of v0.1.1-linux.3, which lists both architectures. Details: Installation.

The GitHub Packages release bundle is not yet available. After a qualified release, it is planned to contain the published assets as an OCI artifact retrievable with ORAS.

Open a new terminal in your project and run ilium. First-run setup walks through AI providers, notification sounds, keyboard practice and an optional voice test. Reopen it with ilium --onboarding or Settings → Guided setup. For this preview, upgrade by installing a newer qualified package.

No Rust toolchain is needed for releases. Use a UTF-8 terminal with 256-colour support and install your agent CLI separately. Linux is the primary platform; macOS and Windows are implemented with different test coverage.

AI privacy: First-run setup lets you choose Kilo Gateway, paid APIs, local Ollama or Skip. Automatic AI requests remain paused until setup finishes. Kilo Gateway sends prompts to its service. See Inference and privacy.

More: Getting started · Building from source

See it in action

Find the next agent that needs you	AI names agents and organizes the project tree
Control Ilium and prompt agents with voice	Give agent panes automatic titles
Transfer a terminal screen between panes	Inspect agent usage and recorded costs
Track agent status and current goals	Use agents, editors, and terminals side by side Historical recording, not embedded (one frame shows an unredacted login-expiry account notice and some frames show scratch-path fragments; keyframe review 2026-11-05). A terminal, editor, and two idle agent panes remain in a split after visiting another pane; setup is cut and an account notice is redacted.
Select and copy terminal output	Queue prompts for an agent
Get results from background tasks Historical recording, not embedded: a scan found local scratch-path text in some frames and no full review was made (see the demo gallery). A real Claude agent monitors a ten-card task.	Search agents, files, and terminals Historical recording, not embedded: a scan found local scratch-path text in some frames and no full review was made (see the demo gallery). Searches real agent output, a shell history and a file.
See live agent goals in the project tree	Recover a session after a simulated reboot
Choose an animation, then watch it play	Schedule input for a pane
Set interface and board preferences	Configure voice and AI providers
Configure automatic titles	Move panes without stopping their processes
Request updates from active agents	Track work on a Kanban board
Start a Codex agent from a TODO Historical recording, not embedded (a scratch path with the local username and a title-inference error are visible; keyframe review 2026-11-05). Start Codex from a TODO line and repair the source. Setup is cut and reading holds are added; automatic title inference reports no user transcript.	Detach and reconnect while agents keep running
Edit Markdown in a pane	Coordinate local models with Chatroom
Respond to confirmation prompts automatically	Restore a saved session
Create an isolated agent worktree	Convert a session between Claude and Codex Historical recording, not embedded: local scratch paths and a plan label are visible in its frames (see the demo gallery). Real Claude and Codex sessions recall a fictional mascot after conversion in both directions.
Queue access to a shared resource

See the full Demo gallery for recording notes and feature guides.

Daily use

Prefix: Ctrl+B.

After prefix	Action
c / e / B	New terminal / editor / board
W	New agent in a Git worktree
g / "	New group / split view
m / ,	Move / rename the selected entry
f	Search agents, terminals, and files
[ / ]	Scroll pane history
: / ?	Settings / key reference
d / &	Detach / kill the session

Run ilium in the project directory to reattach. Press the prefix twice to send a literal prefix key to the focused pane. Remap it in Settings; & ends the session at once, without confirmation.

All keys, mouse use and remapping: Getting started and Panes and layout.

What Ilium does

• Arrange: group panes and split the screen four ways. The project tree stays visible. Panes and layout
• Track: identify agent CLIs from process trees and read activity from terminal screens, with optional model icons in the tree. Choose Normal or Attention status icons, or configure ordered Custom icon rules. Stale activity checks show a caution with their age on hover. Agent monitoring, Custom status icons
• Separate: start agents in linked Git worktrees. Unclear file, process, or ownership state blocks cleanup. Worktrees
• Resume: detach without stopping panes. Recovery rebuilds the layout and relaunches pane programs. Session recovery

Also included:

• An attention queue: one list of the agents that ask you a question, keep failing, wait on another agent, or changed, with a jump button and shortcut.
• Agent cost tracking and notifications.
• Optional remote compaction of Claude and Codex sessions through your Inference model, configured in Settings.
• A compaction optimizer (Settings → Optimization) that scans your Codex and Claude Code transcripts and recommends the cheapest auto-compaction threshold, applied to the agent's own config only after you confirm, with one-click revert. See Settings.
• AI titles, tree organization and custom instructions, with provider and privacy controls.
• Voice control.
• Scheduled input, text triggers, prompt queues, progress monitors and Chatroom.
• Shared resource queues for exclusive GPU and USB-board coordination across projects.
• Editors, boards and Smart Copy.
• Ambient animated backgrounds: landscapes, space, maps, live data, video and more, all sharing one look.

Agent worktrees and recovery in short: start an agent with Ctrl+B W or

ilium new-pane --worktree --branch agent/fix-login -- codex

Several agents can share an existing worktree. With two or more agents, the worktree becomes an expandable leaf-icon row under the project, with its agents fixed beneath it. A single agent keeps the compact branch line.

After a restart, Ilium restores the layout and relaunches pane programs, resuming verified Claude Code, Codex, or Antigravity sessions when provider data remains. Unsaved process state does not survive. Snapshots live in <project>/.ilium/sessions/; add .ilium/ to .gitignore to keep them out of Git.

Command line

Command	What it does
ilium	Attach to or create the current project's default session.
ilium new-session <name> / ilium ls	Create or attach to a named session / list sessions.
ilium new-pane [--keep-open] -- <cmd>	Add a terminal pane without attaching the TUI. The pane closes when the command exits unless --keep-open is given.
ilium chat --help / ilium progress --help	Chatroom and progress commands.
ilium voice say --help	Typed voice input.
ilium ctl <command>	Full remote control for agents and scripts: read the tree as JSON/YAML/Markdown, create, move, rename, close and drive panes. Start with ilium ctl guide.
ilium panes / ilium broadcast <message>	List panes, or message agents, across every running session; filter by project, agent, state, text or regex.

Every command and flag: Command-line reference.

Settings and data

Open Settings with Ctrl+B : and the key map with Ctrl+B ?. Global settings live in ~/.config/ilium/config.toml on Linux. Terminals, agent detection and session storage work without an LLM; AI titles, tree organization and optional Smart Copy suggestions use the provider you choose. File logging is off by default. See Settings and How it works.

Project, help, and licence

Report problems in issues with your version, OS, terminal, command and observed behaviour; remove private content from logs. Design: ARCHITECTURE.md. Contribution rules: CLAUDE.md and Contributing.

Ilium is MIT licensed. The vendored vt100 patch and tui-tree-widget fork retain their MIT licences. Cascadia Code uses SIL Open Font License 1.1; see the font notice.

Blocking failures appear as caution triangles beside affected agents and projects. Hover the triangle to read the cause; unavailable terminals also show their failure reason.