CLI

rostr is a single program for macOS and Linux. Your hooks call it at the start and end of every session, and the rostr skill teaches your agent to use it too.

Concepts

Roster: A named list of agents you can draft from, like your Fellowship or your Smash Bros.
Drafting: A roster's members are in draft order. Each session gets the free member drafted least recently: anyone who hasn't been drafted yet goes first, in roster order. When no one's free, it takes the name of whoever has been resting longest, or else a numbered copy like 🧙 Gandalf 2.
Team size: A pre-built roster is a big cast to pick from. When you assemble one, your team is its first 16, or pick 4, 8, or everyone. Then pick anyone else on that roster, or add your own, in the cast editor.
Local or cloud: Your whole setup lives in one place. Locally, everything is on disk. Once you turn on cloud mode, everything lives on the rostr API at api.getrostr.sh, and every session, on your machine or in a cloud environment, drafts from there. Having a rostr key (saved by rostr cloud on, or set as ROSTR_KEY) is what puts a machine in cloud mode.
Projects: Each git repo can use its own roster. rostr identifies a project by its origin remote (owner/repo), so it's the same project on every machine and in every worktree.
Sessions: Your hooks get each session's ID from Claude Code or Codex and pass it to rostr, so drafting, setting the first task, and releasing all happen without your agent doing anything. The start hook also sets ROSTR_SESSION in the session's shell, so any rostr command your agent runs knows which session it's in.
Which roster gets drafted: The --roster flag on agent commands if you pass one, then the project's linked roster, then your default. Outside a git repo, rostr uses your default.

Roster commands

Set up and manage your rosters.

`rostr assemble`

⭐ The only one you need

rostr assemble [<roster>] [--preset <id> [--size <n>|all] | --names <list>] [--emoji on|off|only] [--cloud] [--no-auto-draft] [--link]

Interactive setup: answer a few questions and you're done. It's the only command you need to run, and your agent can run it for you with flags.

--preset <id>: Skip the preset question. See them all with rostr presets.
--size <n>|all: How many of the preset's members are on your team, from the top of its list. Defaults to 16; all takes everyone. Only with --preset.
--names <list>: Use your own comma-separated names, in draft order, with an emoji in front if you like. Names without an emoji get a random one.
--emoji on|off|only: How agents show up. Defaults to on.
--cloud: Keep everything on the rostr API. Only for your first roster; after that, use rostr cloud on.
--no-auto-draft: Don't draft sessions automatically; use /draft instead.
--link: Use the new roster for the repo you're in. The wizard asks this when you're in a repo.

$ rostr assemble
✔ Pick a preset · 💍 The Fellowship
✔ How big is your team? · 6
✔ Name your roster · work
✔ Emoji · On (🧙 Gandalf)
✔ Where should rostr live? · This machine
✔ Draft every new session automatically? · Yes
✔ Claude Code: hooks, skill, and /draft installed
✔ Codex: hooks and skill installed
💍 Assembled a roster named work. Start a new session to get drafted

$ rostr assemble side --names "🧮 Ada, Grace, Linus, Margaret, Ken, Barbara"
✏️ Assembled a roster named side with 6 members
   🧮 Ada, 🦋 Grace, 🐧 Linus, 🚀 Margaret, 🧵 Ken, 🌻 Barbara

`rostr link / unlink`

rostr link [<roster>] [--repo <owner/repo>]
rostr unlink [--repo <owner/repo>]

Pick which roster your project uses, or unlink it to go back to your default roster. Run rostr link on its own to see which roster this project uses and change it.

💡 Worth it when you want to tell projects apart at a glance: give your side projects the NBA Legends, and Jordan can only mean a side project.

--repo <owner/repo>: Link or unlink a repo other than the current one.

$ cd ~/code/recipes
$ rostr link
✔ me/recipes uses the work roster (your default). Pick one · side
🏀 Linked me/recipes to the side roster

$ rostr link side --repo me/blog
🏀 Linked me/blog to the side roster

$ rostr unlink
Unlinked me/recipes. It now uses your default roster, work

`rostr stats`

rostr stats [<roster>, ...] [--json]

See who's working on what, who's resting, and who's on the bench, across all your rosters. Name rosters to see just those.

--json: Print the result as JSON.

$ rostr stats
work roster
🧙 Gandalf   Fix auth redirect loop         acme/api      12m
💍 Frodo     Flaky e2e tests on CI          acme/web      3m
🌱 Samwise   Migrate billing to Stripe v3   acme/billing  1h
bench: Aragorn, Legolas, Gimli, Boromir, Merry, Pippin

side roster
🐐 Jordan    Port the recipe app to iOS     me/recipes    40m
bench: LeBron, Kobe, Magic, Bird, Curry, Shaq

$ rostr stats side
side roster
🐐 Jordan    Port the recipe app to iOS     me/recipes    40m
bench: LeBron, Kobe, Magic, Bird, Curry, Shaq

`rostr edit`

rostr edit [<roster>]

Add, rename, and remove a roster's members and change their emoji, in a full-screen editor. To swap in a whole new cast, run rostr assemble and replace it.

$ rostr edit work
Saved the work roster.

`rostr presets`

rostr presets [--json]

See all the pre-built rosters you can pass to --preset. They're also on the rosters page, with all their members.

--json: Print every preset as JSON, with all its members in draft order.

$ rostr presets
fellowship       💍 The Fellowship (The Lord of the Rings)
hogwarts         ⚡ Hogwarts (Harry Potter)
smash-bros       🎮 Smash Bros (Super Smash Bros.)
nba              🏀 NBA Legends (Basketball)
rebellion        🌌 The Rebellion (Star Wars)
dunder-mifflin   📎 Dunder Mifflin (The Office)
billionaires     💰 Billionaires (Put them to work)
cs-heroes        🧑‍💻 CS Heroes (Computer science)
seminar          🤔 The Seminar (Philosophy & critical theory)
matrix           💊 The Matrix (Neo vs. the Smiths)
enterprise       🖖 The Enterprise (Star Trek: TNG)
avengers         🛡️ Avengers (Marvel)
westeros         🐉 Westeros (Game of Thrones)
ghibli           🍃 Ghibli (Studio Ghibli)
olympus          🏛️ Olympus (Greek mythology)
kanto            🔴 Kanto (Pokémon)
galactica        🛸 Galactica (Battlestar Galactica)
survey-corps     🪽 Survey Corps (Attack on Titan)
konoha           🍥 Konoha (Naruto)
mlb              ⚾ MLB Legends (Baseball)
nfl              🏈 NFL Legends (Football)
nhl              🏒 NHL Legends (Hockey)
baltimore        📟 Baltimore (The Wire)
rocinante        🚀 The Rocinante (The Expanse)
albuquerque      🧪 Albuquerque (Breaking Bad)
tech-twitter     🐦 Tech Twitter (Posting through it)
free-agents      🎲 Free Agents (Feeling chaotic?)

`rostr disband`

rostr disband <roster> [--yes]

Delete a roster, after asking. Projects that used it fall back to your default, and if it was your default, your oldest other roster takes over.

--yes: Skip the question. Agents need this, since they can't answer it.

$ rostr disband work
✔ Disband work? 3 agents drafted, 1 linked project · Yes
Disbanded work. side is now your default roster

Agent commands

Your hooks, the rostr skill, and the /draft slash command run these.

`rostr draft / bench`

⚙️ On session start and end

rostr draft [--task <description>] [--session <id>] [--json]
rostr bench [<name>, ... | all] [--session <id>]

Draft the next free agent when a session starts, and send it back to the bench when the session ends. The same session always gets the same name back.

--task <description>: What the agent is working on. Shown in rostr stats.
--session <id>: The session to draft or bench for. The hooks pass this, and it defaults to ROSTR_SESSION, then the agent's own session ID.
--json: Print the drafted agent as JSON.

$ rostr draft --task "Fix auth redirect loop"
🧙 Gandalf is on it: Fix auth redirect loop

$ rostr draft --json
{"name": "Gandalf", "emoji": "🧙", "roster": "work", "display": "🧙 Gandalf"}

$ rostr bench gandalf
Benched 🧙 Gandalf from the work roster.

`rostr task`

rostr task [<name>] <description>

Set or change what an agent is working on. Your hooks set the first task from your first prompt.

--session <id>: Set the task for whoever is drafted to this session. The hooks pass this, and it defaults to ROSTR_SESSION, then the agent's own session ID.

$ rostr task "Migrate billing to Stripe v3"
🌱 Samwise is now on: Migrate billing to Stripe v3

$ rostr task samwise "Migrate billing to Stripe v3"
🌱 Samwise is now on: Migrate billing to Stripe v3

Slash command

If you'd rather draft by hand, turn auto-draft off and use this in Claude Code. rostr assemble installs it.

/draft: Draft an agent for this session. Runs rostr draft.

Settings

Change anything you chose during assemble.

`rostr config`

rostr config
rostr config default <roster>
rostr config emoji on|off|only [--roster <roster>]
rostr config auto-draft on|off
rostr config key [--token]

See and change your settings. Run it on its own to see them all.

default: The roster projects use when they don't have a link.
emoji: How agents show up: on (🧙 Gandalf), off (Gandalf), or only (🧙). only needs every member to have a different emoji.
auto-draft: Draft new sessions automatically, or by hand with /draft. It's set per machine; ROSTR_AUTO_DRAFT=off turns it off in a cloud environment.
key: Print your rostr key, which puts a machine in cloud mode. There's no recovery, so keep it safe. --token prints the token for the API instead.

$ rostr config
default      work
emoji        on
auto-draft   on
cloud        off

$ rostr config emoji only
🧙 Emoji only for work. Agents now show as: 🧙 · Fix auth redirect loop

`rostr cloud`

rostr cloud on
rostr cloud install

Keep your setup on the rostr API, so agents on every machine and in cloud sessions share one roster.

on: Move your whole setup to the cloud, or join one with your key (which installs rostr's hooks on this machine too). Turn it on once, when you start using cloud agents. There's no going back to local.
install: Install rostr's hooks for Claude Code and Codex in a cloud environment. The install script runs this for you when ROSTR_KEY is set in your cloud environment.

$ rostr cloud on
✔ New setup, or do you have a key? · New setup
☁️ Moved your setup to the cloud
   2 rosters, 3 project links, 4 active drafts
   Saved your rostr key to ~/.config/rostr/credentials
   Run rostr config key to see it, then set it as ROSTR_KEY in your cloud environments

CLI

Concepts

🎯 Roster commands

rostr assemble

rostr link / unlink

rostr stats

rostr edit

rostr presets

rostr disband

🤖 Agent commands

rostr draft / bench

rostr task