Run a fleet of coding agents from Emacs. Roost gives each agent (Claude Code, Codex, Pi or OpenCode) a task of its own: a Git worktree, a branch and a terminal, here or on any SSH host. It tells you which agents need you, and you review and merge their work with Magit. If you've used Orca, it's that idea, inside Emacs.
Nine agents on two hosts: every task at the left, one agent's terminal in the middle, and what to do next at the right.
C-c r is Roost's menu, as in the setup below.
-
Start where the work is.
C-c r con an Org heading drafts a task with the heading and its notes as the prompt; a region, a GitHub issue or a Jira work item works the same way.C-c C-cstarts the agent in a worktree and branch of its own. -
Go where you're needed.
C-c r ntakes you to the next agent waiting for you, and you answer it in its own terminal. With perspective.el ortab-bar-mode, each task has a perspective or tab of its own. -
Review, and reply in place. The panel beside the terminal lists the files the agent changed. Click one for its diff in Magit, write a note on a line with
;, and send your notes to the agent with@. -
Finish. Once the agent has committed,
C-c r msquashes the task into the branch it started from and removes its worktree, branch and terminal.C-c r Popens a pull request instead.
Or talk first. C-c r C opens an agent in no project. Ask it to plan a
piece of work, and each task it proposes waits under the conversation, a
click away from a draft.
Watch them all. M-x roost-dashboard lists every agent on every host:
what it's doing (Running make test), what it changed, and its latest reply
or what it asks. A notification says when one finishes or asks.
When an agent has a picture for you, Roost opens it beside its terminal.
Images. Ask for a plot, a screenshot, or a before and an after. The agent shows up to six together, and a click on one fills the frame.
Pages. With (setq roost-agent-pages t), an agent in a new task can
also write a small page: a diagram you can click, a mock-up, controls to
try. Pages need a graphical Emacs built with xwidgets.
As it is written. A Pi task on this machine shows its page as the model writes it, when the model's server sends it piece by piece, as OpenAI's did here (played at twice its speed).
Pi also draws the images it reads inside its terminal, as in the picture at the top. The manual has the keys, sizes and limits.
Roost needs Emacs 29.1+, and Ghostel 0.65.0+ and ghostel-tmux 0.4.0+ to draw the terminals. Each host needs Python 3.9+, Git, tmux 3.1+ and a signed-in agent CLI; remote hosts need SSH with keys or an agent. With Emacs 30:
(use-package ghostel :ensure t) ; from MELPA
(use-package ghostel-tmux
:vc (:url "https://github.com/dakra/ghostel-tmux" :rev :newest))
(use-package roost
:vc (:url "https://github.com/csheaff/roost" :rev :newest)
:demand t
:bind ("C-c r" . roost-dispatch) ; the menu, from anywhere
;; :custom (roost-hosts '(nil "devbox")) ; SSH hosts too; nil is this one
:config
(roost-watch-mode 1) ; notice waiting agents from startup
(roost-sidebar-mode 1) ; the task list at the left
(roost-task-panel-mode 1)) ; a task's panel beside its terminalGhostel offers to download its native module the first time a terminal opens. The manual covers straight.el, Doom, Emacs 29, Evil and other modal setups.
M-x roost-doctorchecks this machine and each host, with a fix for anything missing.- In a Git project,
C-c r c, write a prompt, andC-c C-c. - Answer the agent in its terminal.
C-c ?there opens Roost's menu.
| Key | Key | ||
|---|---|---|---|
c |
New task | r |
Review in Magit |
n |
Next agent waiting for you | u |
Bring a task up to date |
RET |
The agent's terminal | m |
Merge it, and retire it |
t |
A shell in its worktree | P |
Open a pull request |
e |
Send the agent a prompt | x |
Retire it, or discard it |
/ |
Search agents' conversations | ? |
Every command |
These work on the menu, and alone in the dashboard, the sidebar and a task's panel.
- Agents run in tmux, each in its own terminal interface: its prompts, menus and slash commands work as always. Restart Emacs and they are still at work; close the laptop and remote ones carry on.
- Roost never answers an agent's prompts, never changes your global agent settings, and never stages or commits your work. It deletes work only when you discard a task and type its name.
- Roost is built around Claude Code and checked against each new release.
Codex, Pi and OpenCode tasks show the same statuses; Codex asks before
each commit, and its approvals show only once it moves on unless
roost-program-statusis on. - Claude Code 2.1.284+ starts in auto mode and rarely asks. To be asked
before each command, add
"--permission-mode" "manual"to its entry inroost-agent-commands. - Each agent gets three tools from Roost, to offer you tasks, name your
projects and show you images;
(setq roost-agent-offers nil)starts tasks without them. (setq roost-remote-control t)shows each Claude task in the Claude app, which notifies your phone when its agent needs a decision.
- The manual: every command and option, and how Roost works.
- Changes, with what to do when upgrading.
- A possible roadmap, and the research behind it.
- Validation runs, how the screenshots were made, and the MELPA recipes.
Orca shaped the workflow; see the comparison.
GPL-3.0-or-later.






