Roost

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.

Six Claude Code agents on two machines. The one on claylien wants to run its tests: its own terminal in the middle, every task at the left, and at the right what to do next, what you asked it and what it changed.

A task, start to finish

One task, from a heading in an Org file to main. C-c r opens Roost's menu, as in the setup below; in the dashboard, the sidebar and a task's panel its keys work alone.

1. Start where the work is. C-c r c on an Org heading drafts a task, with the heading and its notes as the prompt; a selected region or a GitHub issue works the same way. C-c C-c makes the worktree and branch and starts the agent.

   

2. Go where you're needed. While it works, an agent on claylien asks to run its tests. C-c r n takes you to the next agent waiting for you, and you answer it in its own terminal. With perspective.el or tab-bar-mode on, each task has a perspective or tab of its own, which keeps its terminal, diffs and files together as you left them.

3. Review, and reply in place. The panel beside the terminal lists the files the agent changed, and the other tasks that change them too. A click opens one's diff in Magit, ; writes a note on a line, and @ in Magit, or e, sends your notes to the agent. C-c r r opens Magit on the whole worktree, over TRAMP for a remote task.

   

4. Finish. The agent revises and commits. C-c r m squashes the task into the branch it started from and removes its worktree, branch and terminal. On the same menu, u brings a task up to date first, and P opens a pull request instead.

Watch them all. M-x roost-dashboard lists every agent on every host: what it's doing, what it changed, and its latest reply or what it asks. A notification says the same when one finishes or asks for something.

How it differs

Other Emacs packages run coding agents too, among them agent-shell, claude-code.el and M-x Machina. Roost differs in three ways:

• Agents run outside Emacs. Each one runs in tmux, and Emacs shows its terminal. Restart Emacs, and an agent at work is still at work, rather than resumed from its saved conversation.
• On any machine you can reach over SSH. One dashboard covers this machine and your remote hosts, and Magit reviews their work over TRAMP, fastest with tramp-rpc. Close the laptop, and a remote agent carries on.
• It sees a task through. Each task has its own worktree and branch. You review it in Magit and send notes on its lines back to the agent; Roost brings it up to date, merges it or opens a pull request, and cleans up.

Each agent keeps its own terminal interface, so its prompts, menus and slash commands work as they always do, new ones included. Roost adds what lives outside the agent.

Get started

Roost needs Emacs 29.1 or newer and tmux-control 0.8.2 or newer. 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 tmux-control
  :vc (:url "https://github.com/csheaff/tmux-control" :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 terminal

For straight.el, Doom, Emacs 29, Evil and other modal setups, see the manual.

1. M-x roost-doctor checks this machine and each host, with a fix for anything missing.
2. In a Git project, C-c r c, write a prompt, and C-c C-c.
3. 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 in the dashboard, the sidebar and a task's panel, and on the menu.

Good to know

• Roost is built around Claude Code and checked against each new release of it. 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-status is 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.
• Claude Code 2.1.284 and later start in auto mode unless a permission mode is set, and rarely ask. To be asked before each command, add "--permission-mode" "manual" to its entry in roost-agent-commands.

More

• The manual: every command and option, a day of work in detail, and how Roost works.
• Changes, with what to do when upgrading.
• A possible roadmap: ideas being considered, and the tools and research they come from.
• Validation: live runs with Claude Code and Codex, on local and remote hosts. How the screenshots were made, and the MELPA recipes.

Orca shaped the workflow: a worktree per task, a terminal nearby, review before finishing. See the comparison.

License

GPL-3.0-or-later.