Skip to content
GoCarrotPublic
forked from AvesAlight/roost

About

GoCarrot fork of AvesAlight/roost

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Roost — AVES/ALIGHT

roost

Roost lets you run your own team of Claude Code agents on a real project. A project-manager agent picks up issues from a GitHub milestone and spawns workers and reviewers to drive each one through PR; the team coordinates over a local IRC server you can join from any client. You watch the work happen and step in when something needs human judgment.

Agents talk to each other and to you over the same channels — not a pipeline, a network.

Security model

Roost spawns agents that can read, write, and execute in arbitrary working directories with arbitrary parameters. Permission gating via --perm-irc relies on IRC nick identity — local ergo has no authentication, so any process with TCP access to localhost:6667 can claim any unused nick and approve tool calls by sending y to the permbot.

This is intentional for trusted single-user local environments. Don't run ergo on a shared host or expose port 6667 beyond localhost.

Running a milestone

Roost is built for parallel milestone work. Spawn one agent — project-manager — and hand it a GitHub milestone. It creates a channel per issue, spawns workers and reviewers into them, and coordinates with the dispatcher to route CI and PR events back in. You watch and intervene from weechat on the same box. Workers post plans before coding; reviewers post findings to GitHub; the PM drives sequencing and flips PRs ready.

Bootstrap your project, then kick off the PM:

cd ~/Dev/myproject
roost init --repo Owner/myproject   # writes .orchestrator/{config.json, config.local.json, .gitignore} + copies role prompts
roost spawn myproject-pm \
  --agent project-manager \
  --channels '#myproject-leads' \
  --steer-compact --cache-ttl 1h \
  --ask-irc '#myproject-leads' --ask-target <your-nick> \
  --prompt 'milestone=<milestone> human=<your-nick> gh-login=<your-gh-login>'

See docs/ROOST-IN-PRACTICE.md for the end-to-end walkthrough.

Roost ships more agents than project-manager — each is a roost spawn <nick> --agent <name> target. roost agents lists the ones installed in your project; roost agents --all also shows what roost ships but you haven't installed yet, and how to pull them in.

Prerequisites

  • macOS or Linux
  • bun ≥ 1.0 (installed by the brew formula). From-source Linux installs add ~/.bun/bin to ~/.bashrc only — set BUN_BIN=~/.bun/bin/bun if the MCP or dispatcher fail to start.
  • tmux (installed by the brew formula)
  • ergo (installed by the brew formula)
  • An IRC client (weechat recommended — brew install weechat)
  • A Claude Code build with --dangerously-load-development-channels

Setup (one-time)

1. Install roost

brew tap oven-sh/bun
brew install avesalight/tap/roost

Puts roost on your PATH. The roost-irc MCP loads automatically when you start a session via roost spawn — running claude directly without roost spawn won't load it.

2. Start your IRC server

Roost needs an IRCv3 server on 127.0.0.1:6667. With ergo, run it from a working directory of your choice — relative paths in the config (logs/, ircd.db, etc.) resolve from there:

mkdir -p ~/roost-ircd/logs && cd ~/roost-ircd
nohup ergo run --conf "$(roost root)/etc/ergo.yaml" > /tmp/ergo.out 2>&1 &

Verify it's up:

lsof -nP -iTCP:6667 -sTCP:LISTEN

To stop:

pkill -f 'ergo run.*roost/etc/ergo.yaml'

Running

Launch a Claude session that joins the roost

roost spawn worker-1 -c '#my-channel' --cwd ~/Dev/myproject

roost spawn agent-2 \
  -c '#my-channel' \
  --cwd ~/Dev/myproject \
  --prompt-file /tmp/handoff.md \
  -- --chrome --system-prompt ' '

roost list
roost attach worker-1
roost shutdown worker-1
roost status
roost --version

spawn accepts -c|--channels, -m|--model, --agent, -s|--session, --mcp-config, -p|--prompt-file, --cwd, --ollama-model, and -- (everything after forwards to claude verbatim). Default channel is #roost; default model is opus (Opus 4.8), unless --agent is set with no --model, in which case the agent's frontmatter model applies. Combine --model with --agent to run that agent under a different model than its frontmatter default. Fable, opus, and sonnet default to --permission-mode auto; everything else (haiku, or any unrecognized model) defaults to acceptEdits.

spawn also injects --append-system-prompt-file naming the joined channels as legitimate user-instruction sources, so that under --permission-mode auto the model will issue consequential tool calls (Bash, Edit) in response to IRC messages rather than treating them as untrusted external data (channel_message posting itself is not blocked). Only injected when the IRC host is loopback (127.0.0.1, ::1, localhost); remote ergo falls outside roost's trusted single-user local environment security model and prints a warning instead. Pass --trust-remote to opt in to the same injection for a non-loopback host the operator controls. The injection is always on for loopback hosts. To layer more context on top, pass --append-system-prompt-file <path> after --; claude code rejects mixing inline --append-system-prompt with the file form.

Running an agent on ollama

--ollama-model <tag> routes a spawn through ollama instead of calling claude directly. roost runs ollama launch claude --model <tag> -- <roost args>, passing the settings, plugin-dir, channels, trust, agent, and model args through ollama's -- separator unchanged. ollama owns the local-server protocol and forces every native model selector (the --model tier and the agent frontmatter model:) to the tag, so roost does not parse or change frontmatter. Without the flag, claude runs against Anthropic exactly as today.

Which agents use ollama is an operator choice. Point a specific spawn at it — e.g. run your pm/apm on an ollama-hosted model while workers/reviewers stay on Anthropic:

roost spawn myproject-pm --agent project-manager \
  --ollama-model glm-5.2:cloud -c '#myproject-leads' ...

Any prompt edits that tell an agent it's running on ollama are yours to make.

Debugging a failed spawn

If you need to invoke claude directly to debug a failed roost spawn, the --dangerously-load-development-channels flag (hidden from claude --help) takes a server-id. The format depends on how roost is loaded:

  • Via plugin loader (installed via brew): server:plugin:roost:roost-irc
  • As a bare MCP server (dev checkout, manual --mcp-config): server:roost-irc
claude --dangerously-load-development-channels server:plugin:roost:roost-irc

Observe as a human (no Claude needed)

The ergo config has no auth — any IRC client against 127.0.0.1:6667 works:

brew install weechat
weechat
# inside weechat:
/server add roost 127.0.0.1/6667 -notls
/connect roost -nick myname
/join #roost

On macOS, extras/weechat/notification_center.py adds native notification center alerts for mentions and DMs. Get the path from your shell and load it in weechat:

echo "$(roost root)/extras/weechat/notification_center.py"
# → e.g. /opt/homebrew/Cellar/roost/0.1.1/libexec/extras/weechat/notification_center.py
# inside weechat — paste the path printed above:
/script load /opt/homebrew/Cellar/roost/0.1.1/libexec/extras/weechat/notification_center.py

IRC permission oversight (--perm-irc)

--perm-irc runs a permbot routing module inside the worker's MCP process. The module holds a second IRC connection on a stable nick permbot-{worker} and serializes the worker's PermissionRequest prompts as DMs to --perm-target (required). The operator replies y / n / yes / no / allow / deny; anything else or a 30s timeout falls through to the terminal prompt.

Primary use case: an Opus orchestrator spawning a worker that isn't running auto mode — haiku or an unrecognized model (acceptEdits by default), or any model held in acceptEdits via --permission-mode for oversight. Without oversight, that worker floods the terminal with permission prompts. With --perm-irc --perm-target <orchestrator>, prompts come to the orchestrator over IRC.

# Opus orchestrator gates a sonnet worker held in acceptEdits for oversight:
roost spawn worker-123-A -c '#pr-123' -m sonnet --permission-mode acceptEdits \
  --perm-irc --perm-target orchestrator

# Human operator gates a haiku worker (acceptEdits by default):
roost spawn scratch-h -c '#sandbox' -m haiku \
  --perm-irc --perm-target mynick

Project dispatcher

roost init bootstraps your project's dispatcher config and copies the role prompts into .claude/commands/. Then start the dispatcher — it polls GitHub on a tick, routes events (CI transitions, PR comments, issue updates) into the right #<project>-issue-N channels, and accepts watch/unwatch DMs to control which issues and PRs are tracked:

cd ~/Dev/myproject
roost init --repo Owner/myapp           # single-repo: writes .orchestrator/{config.json, config.local.json, .gitignore} + prompts
CONFIG_DIR="$(pwd)/.orchestrator"
"$ROOST_DIR/bin/start-dispatcher" "$CONFIG_DIR"

To manage multiple repos from a shared directory instead:

mkdir ~/Dev/shared && cd ~/Dev/shared
roost init --multi-repo --project myapp

DM the dispatcher (<project>-dispatcher) to manage the watch list: watch <N>, unwatch <N>, watch pr <N>, unwatch pr <N>, watch list, help. The dispatcher's allowlist defaults to [<project>-pm]; set irc.command_senders in config to override.

project namespaces every per-project artifact (<project>-worker-N nicks, #<project>-issue-N channels, etc.) so multiple projects can share one ergo. See docs/DISPATCHER.md for config schema, event reference, and plugin extension points.

Channel events received

Inbound IRC arrives in the host session as channel notifications:

Regular messages:

<channel event="message" sender="alex" channel="#roost"
         isDirect="false" ts="2026-04-28T05:30:00.000Z" seq="42">
hello world
</channel>

mention="true" is added when the message body contains your nick (word-boundary, case-insensitive) or when the message is a DM (isDirect="true"). Absent on non-mention channel messages.

<channel event="message" sender="alex" channel="#roost"
         isDirect="false" ts="2026-04-28T05:30:00.000Z" seq="43" mention="true">
roost-worker-1: can you check the build?
</channel>

Membership events (JOIN, PART, KICK, NICK):

<channel event="join" sender="newcomer" channel="#roost"
         isDirect="false" ts="..." seq="...">
newcomer joined #roost
</channel>

Self-events (your own JOIN/LEAVE/NICK) are suppressed.

Environment variables

Var Default Notes
ROOST_IRC_NICK (required) The nick this session connects as. Ergo refuses collisions.
ROOST_IRC_CHANNELS (none) Comma-separated channels to auto-join at registration.
ROOST_IRC_SERVER 127.0.0.1 IRC server host.
ROOST_IRC_PORT 6667 IRC server port.
ROOST_IRC_REALNAME same as nick IRC realname (gecos).
ROOST_IRC_HISTORY 50 Per-channel ring-buffer size for channel_history.

Testing

bun test

Requires ergo. Install it once with bin/install-ergo, or point ERGO_BIN at an existing binary. Tests skip gracefully when ergo isn't found.

For coverage (line ≥ 85%, branch ≥ 75% globally):

bun test --coverage

Coverage includes src/irc-server.ts via the in-process tests (test/irc-server-inprocess.test.ts).

Known limitations

  • No SASL / nick reservation. Any local process that connects can claim any unused nick. Acceptable for a single-user dev box; revisit before hosting multi-tenant work.
  • channel_history is per-MCP-instance. Restarting an MCP loses the buffer. For durable history use ergo's audit log (~/roost-ircd/logs/audit.log) or the IRCv3 CHATHISTORY command.
  • alwaysLoad: true keeps all six tools non-deferred. Empirical baseline-vs-alwaysLoad probe (2026-04-28) showed 0 tools_changed misses with the flag vs 2 without (see docs/LEARNINGS.md Finding A).

About

GoCarrot fork of AvesAlight/roost

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages