Retrieved article excerpt
Open article · Retrieved 2026-09-20T13:22:17.635830+00:00
# [Runner](https://github.com/yicheng47/runner/blob/main/assets/icon.png) Runner
[GitHub stars](https://github.com/yicheng47/runner/stargazers)
[Downloads](https://github.com/yicheng47/runner/releases)
[License](https://github.com/yicheng47/runner/blob/main/LICENSE)
[WeChat user group](https://github.com/yicheng47/runner#community)
[macOS and Windows](https://github.com/yicheng47/runner#download)
English · [简体中文](https://github.com/yicheng47/runner/blob/main/README.zh-CN.md)
**Where terminal agents work together.**
Claude Code, Codex, Copilot CLI, pi and TRAE on the same task, in one mission. Each agent keeps its own TUI in a real terminal; Runner is what sits between them.
[**Download Runner**](https://github.com/yicheng47/runner/releases/latest)
[Runner — one tab with Claude Code, GitHub Copilot CLI, TRAE CLI and Codex in four panes, projects and chats in the sidebar](https://github.com/yicheng47/runner/blob/main/assets/hero.png)
[About](https://github.com/yicheng47/runner#about)
·
[Features](https://github.com/yicheng47/runner#features)
·
[Agents](https://github.com/yicheng47/runner#supported-agents)
·
[MCP](https://github.com/yicheng47/runner#mcp-servers-and-skills-managed-in-one-place)
·
[Crew example](https://github.com/yicheng47/runner#example-crew)
·
[Download](https://github.com/yicheng47/runner#download)
·
[Documentation](https://github.com/yicheng47/runner#documentation)
·
[Contributing](https://github.com/yicheng47/runner/blob/main/AGENTS.md)
> Status: alpha, actively shipping. Native macOS (Apple Silicon) and Windows (x64), with Windows support starting in 0.8.0.
## About
Runner is a native desktop app for running CLI coding agents **together**. Running several at once is already easy — give each one a terminal and they work in parallel, isolated from one another. Runner is for the other thing: one task, different roles, a shared feed, and one lead who pulls you in when the decision is yours. It is opinionated about the workflow and neutral about the provider, so your coder can be Claude Code and your reviewer Codex.
- **Role** — a reusable agent configuration: runtime, system prompt, working directory.
- **Crew** — roles composed into named slots with one lead, plus the team conventions every mission inherits.
- **Mission** — a crew working one goal: one live terminal per slot, coordinating over an event feed that persists and replays, with `ask_human` when a decision is yours.
- **Chat** — a single agent in a real terminal, no mission required; split a tab as far as the window allows.
- **CLI** — everything above is a command too, so agents, scripts, and people at a terminal can drive Runner themselves.
Written in Rust on [gpui-ce](https://github.com/gpui-ce/gpui-ce), the community fork of [Zed](https://zed.dev)'s GPUI, with `alacritty_terminal` for the grid and SQLite for state. No webview. Everything runs and persists on your machine.
## Download
Grab the latest build from the [releases page](https://github.com/yicheng47/runner/releases/latest): a signed and notarized `.dmg` for macOS on Apple Silicon, and a signed `Runner-Setup-…-x64.exe` installer for Windows 10 version 1809 or later. Intel Macs, Windows ARM64, and Linux are not supported.
Both platforms update in place, macOS through Sparkle and Windows through the update icon beside Settings, and keep your settings, chats, and missions. On Windows, SmartScreen may still warn on a fresh release while the certificate builds reputation; **More info → Run anyway** continues.
Want what landed today instead? The [`nightly` prerelease](https://github.com/yicheng47/runner/releases/tag/nightly) is built from `main` for both platforms, signed the same way, and updates on its own channel.
## Community
- Bugs and feature requests: [GitHub Issues](https://github.com/yicheng47/runner/issues).
- 中文用户可以扫码加入 Runner 微信用户群。群二维码 7 天过期，如果扫码提示失效，请[提一个 issue](https://github.com/yicheng47/runner/issues/new) 提醒我更新。
[Runner 微信用户群二维码](https://github.com/yicheng47/runner/blob/main/assets/wechat_group_qr.png)
## Demo
A three-agent crew — two players and a referee — playing a game of tic-tac-toe against each other over the mission feed, from the [`tic-tac-toe`](https://github.com/yicheng47/runner/blob/main/examples/tic-tac-toe) example crew.
runner-tic-tac-toe.mp4
[
](https://private-user-images.githubusercontent.com/84785168/648374926-fb3669a4-010d-42d0-9555-2a3ba3223c75.mp4?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3ODk5MTA4MzcsIm5iZiI6MTc4OTkxMDUzNywicGF0aCI6Ii84NDc4NTE2OC82NDgzNzQ5MjYtZmIzNjY5YTQtMDEwZC00MmQwLTk1NTUtMmEzYmEzMjIzYzc1Lm1wND9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNjA5MjAlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjYwOTIwVDEzMjIxN1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTQwNzQ1MTQyMjlmMGM5NzM0NGU5YzI4ZmEzM2Q2YTIxOWJhODEwZGY1YTJjMjIyOWQ3MTI1MjJlMWY0ZmQyMTQmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JnJlc3BvbnNlLWNvbnRlbnQtdHlwZT12aWRlbyUyRm1wNCJ9.d84fcmm4hF9GikEhsELXTi8LH_k-qER6cuzUNYkGXhI)
## Features
| | |
| --- | --- |
| [Roles — reusable agent configurations, each with its runtime, command, and the crews and sessions using it](https://github.com/yicheng47/runner/blob/main/assets/roles.png) [Crews — codex-crew and claude crew, each a coder lead and a reviewer drawn from roles](https://github.com/yicheng47/runner/blob/main/assets/crews.png) | Crews — roles, prompts, one lead A **role** is a reusable agent configuration: runtime, system prompt, working directory. A **crew** composes roles into named slots with exactly one lead, plus team conventions and a definition of done that every mission inherits. |
| [Mission workspace — the event feed between crew and human](https://github.com/yicheng47/runner/blob/main/assets/mission_feed.png) [Mission workspace — one slot's live terminal](https://github.com/yicheng47/runner/blob/main/assets/mission_terminal.png) | Missions — a crew working one goal Starting a mission spawns one live PTY per slot into a tabbed workspace. The **feed** is where the crew coordinates: an append-only event log, every signal persisted and replayable, so missions survive a quit or crash, and `ask_human` questions surface there for you. Each **slot** is a real terminal one tab over, the agent's own TUI, where you can watch, type, or stop, resume, and restart that session on its own. [Architecture →](https://github.com/yicheng47/runner/blob/main/docs/arch/arch.md) |
| [Chat tab with four split panes and organized sidebar](https://github.com/yicheng47/runner/blob/main/assets/chat_split.png) [Dragging a pane by its grip — the highlighted half of the target shows where it lands](https://github.com/yicheng47/runner/blob/main/assets/chat_drag.png) | Chats — tabs, split panes, folders Every chat is a real 1:1 PTY with a role, no mission required. Split a tab as far as the window allows — right or down from any pane, `⌘D` and `⇧⌘D` — and drag a pane by its grip to reorder; terminal tabs split the same way, straight into another shell. The sidebar groups tabs into collapsible folders; every tab shows a spinner while a pane is still working and a dot when one finished while you were elsewhere, so a wall of parallel agents stays scannable. |
| [A zsh drawer open beneath a tab with Claude Code and Codex side by side, in the same directory](https://github.com/yicheng47/runner/blob/main/assets/terminal_drawer.png) | Terminal drawer Every chat and every mission has a shell beneath it, one shortcut away, opened in the same directory as the agent above. Run the tests the agent just wrote, check `git status`, tail a log, without leaving the pane or opening another terminal app. Drawers hold as many shells as you need and come back where you left them. |
| [Two Runner windows, a Claude Code chat in front and a Codex chat behind](https://github.com/yicheng47/runner/blob/main/assets/multi_window.png) | Multi-window `⇧⌘N` on macOS or `Ctrl+Shift+N` on Windows opens additional OS windows — a mission on one screen, a wall of chats on the other. Windows coordinate ownership of shared sessions: the primary owns the PTY, and any other window showing the same session gets a hand-off overlay instead of a corrupted terminal. |
| [Settings → MCP — every MCP server each agent has](https://github.com/yicheng47/runner/blob/main/assets/mcp_settings.png) [Settings → Skills — every skill an agent can load, with a toggle per skill](https://github.com/yicheng47/runner/blob/main/assets/skills.png) | MCP servers and skills, managed in one place Each agent keeps its MCP servers and its skills in its own config files. **Settings → MCP** and **Settings → Skills** read those files and show them as one list per agent: pick Claude Code or Codex, see everything it has, flip a toggle to switch a server or a skill off for that agent's new sessions, click a skill to read it or edit it. Runner changes only the one entry you touched and leaves the rest of the file exactly as you wrote it. Drive Runner from your agents The bundled `runner` command is the one way agents, scripts, and people at a terminal drive the app: create projects, roles, and crews; start missions and chats; follow the feed; answer questions; and manage their lifecycle. On macOS, the first launch installs it to `~/.local/bin`, or a writable `/usr/local/bin`, when that directory is already on the login `PATH`; otherwise it is one click in **Settings → General → Command line**. On Windows, Runner adds its sidecar directory to the user `PATH`. Agents need no setup. Runner installs a `runner` skill for every detected agent into three roots that cover all five runtimes: `~/.claude/skills/` for Claude Code, `~/.agents/skills/` for Codex, GitHub Copilot CLI, and pi, and `~/.trae/skills/` for TRAE CLI. The skill points the agent at the version-matched `runner help agents` guide. The same **Command line** section has the `runner` command row and the **Runner skill for agents** switch. ``` runner crew list --json mission=$(runner mission start --crew <crew> --goal-file - -q < brief.md) runner mission feed "$mission" --follow --json runner mission show "$mission" --json runner msg post --mission "$mission" --to <lead_handle> "message" runner mission answer "$mission" <question_id> <choice> runner mission stop "$mission" runner mission archive "$mission" ``` Agents use `--json`; without it, list and show commands render tables and readable summaries for people. Exit status 0 is success, 1 means Runner refused the operation, 2 is a usage or reference error, 3 means the app is not running, and 5 means a sandbox blocked the local connection. Inside a mission, the same binary takes its mission and handle from the environment and is how crew members message and signal each other. The part that compounds: your daily agent can plan a fix, dispatch a coder and reviewer crew to build it, and keep working, while every session it spawned is still a real terminal you can open and watch. |
| [Runner in Runner Light — a Claude Code chat on the light theme](https://github.com/yicheng47/runner/blob/main/assets/light.png) [Settings → Appearance — light and dark previews with an app and a terminal palette per mode](https://github.com/yicheng47/runner/blob/main/assets/appearance.png) | Light and dark, designed for Runner Carbon and Runner Light are Runner's own themes; Catppuccin Mocha and Latte ride along. Auto follows the OS, Light and Dark pin it, and a Claude Code chat follows the flip the moment it happens, no restart, no `/theme`. A palette per mode, previewed **Settings → Appearance** picks an app palette and a terminal palette for light and for dark above a live preview of both modes, so a light app gets a light terminal without a second setting. Rosé Pine Dawn is the default light terminal. |
### Also in the box
- **Sessions that outlive the app** — quitting or crashing does not kill