yicheng47/runner

Runner – A native desktop hub for AI coding agents

What it is Runner is a macOS‑and‑Windows native application that lets you run multiple AI‑powered coding assistants (Claude Code, Codex, Antigravity CLI, GitHub Copilot CLI, pi, etc.) side‑by‑side in real terminal panes. It organises those agents into crews (reusable role collections) that share a mission feed, coordinate via a chat‑like interface, and keep their own PTY sessions alive even when the UI is closed.

Key features

Feature	What you get
Reusable crews	Save a set of roles (e.g., coder, reviewer, QA) with a designated lead and shared conventions; launch the same team on any project with one click.
Missions & coordination	A live mission feed shows messages from every crew slot, lets agents ask you questions, and lets you pause, resume or restart individual slots without affecting the rest.
Real terminals	Each agent runs in its own PTY backed by the alacritty_terminal grid, supporting mouse, IME input, file‑path clicks and a shell drawer beneath every chat.
Split tabs & windows	Drag‑and‑drop panes, split a tab arbitrarily, group tabs into folders, and open additional windows (⌘⇧N / Ctrl+Shift+N).
Desktop notifications	Get OS notifications when an agent needs input, finishes a turn, or fails; clicking jumps straight to the relevant chat or mission.
Background service (runnerd)	Sessions persist in a daemon; close the UI or crash and your terminals resume exactly where they left off.
MCP servers & skills pane	Centralised view of each agent’s configuration, with per‑agent toggles, version display and one‑click updater.
Projects	Bind a working directory once; all chats and missions started there inherit the cwd and appear together in the sidebar.
Theming	Light, dark, and Catppuccin palettes; the UI and the embedded terminals switch together.

How you use it

1. Install the agents you want (Claude Code, Codex, Antigravity CLI, Copilot CLI, pi, etc.) and make sure they are on your PATH.
2. Download Runner (native macOS Apple Silicon or Windows x64) from the website or the Releases page.
3. Create a crew – pick roles, assign an agent to each slot, set a lead and optional overrides.
4. Start a mission – Runner opens a split‑screen UI where each slot has its own terminal and a shared feed for coordination.
5. Interact – Answer questions, approve actions, or let the agents run autonomously. When you’re done, close the app; the background daemon keeps everything alive.

CLI control Runner mirrors every UI action with a runner command, so scripts or other agents can drive it:

# launch a mission from a script
mission=$(runner mission start --crew pair-coding --goal-file - -q brief.md)
runner mission feed "$mission" --follow   # stream live messages
runner msg post --mission "$mission" --to lead "Got it"
runner mission answer "$mission" <question_id> <choice>
runner mission stop "$mission"

All commands support --json for machine‑readable output, making it easy to integrate into automation pipelines.

Supported agents (as of the latest release) include:

• Codex, Claude Code, Antigravity CLI, pi, GitHub Copilot CLI, Cursor, Grok (macOS only), and optional TRAE CLI.
• Agents are detected automatically; you can override the executable path, view version info, and update them from Settings → Agents.

Installation

• macOS – first launch installs runner to ~/.local/bin (or /usr/local/bin if writable). You can also add it manually via Settings → General → Command line.
• Windows – the installer adds runner.exe to the user PATH.
• No additional runtime is required; Runner only orchestrates the CLIs you already have.

Community & support

• Issues & feature requests: https://github.com/yicheng47/runner/issues
• Chinese‑language user group on WeChat (QR code in the repo).
• Contributions are welcome via the CONTRIBUTING.md guide.

License MIT license (2026‑present). Earlier releases (2026‑08‑22 to 2026‑09‑22) were GPL‑3.0‑only and remain available under that license.

---

Bottom line – Runner is a purpose‑built desktop orchestrator for AI coding assistants, turning a collection of separate CLI agents into a coordinated, persistent, and UI‑rich development crew.