A lightweight operator agent framework. A CLI that scaffolds role-based agents — GTM, product, design, ops — into your existing AI coding tool, and runs them on schedules with human approval before anything ships.
● 7am Monday. Three agents have already run while you slept.
│
● gtm/sdr last night's signups triaged · 5 personalized intros queued
● product/pm 3 competitor changelogs summarized · LinkedIn post drafted
● design/critic yesterday's PR screenshots audited · 2 contrast issues flagged
│
✓ All parked in your approval queue. You approve, edit, or reject over coffee.
| Pillar | What it means |
|---|---|
| Lightweight | One npm install. No servers, no databases, no SaaS layer. Tiny tarball, no proprietary DSL — your workspace is just markdown and YAML you own and can hand-edit. |
| Subscription-safe | Runs on the flat-rate Claude Code or Codex CLI subscription you already pay for. No per-token API bills, no third-party agent platform. |
| Operator-first | Built by someone running a real business. GTM, product, design, and ops are first-class roles — not a chatbot wrapped in marketing copy. |
| Schedule-native | Agents run on cron-like schedules through your host tool's native scheduler. Daily morning runs, weekly competitor sweeps, PR-triggered design QA. |
| HITL by default | Risky outputs (emails, PR comments, social posts) land in pending/ queues. Nothing ships until you say so. |
npx @firatcand/roster installInteractive — prompts for which AI tools to set up (Claude Code, Codex CLI, Gemini) and which scope (workspace-local vs. user home). Run inside a roster init workspace to get the project-local default; run from anywhere else for user-scope. macOS, Linux, and Windows. For non-interactive contexts (CI / scripts), add --yes plus --tool <name> and --scope <project|user> to skip prompts.
Want the agent to do the install for you? Paste this into Claude Code, Codex, or Cursor:
Set up https://github.com/firatcand/roster for me. Read install.md and follow
the steps to install roster and scaffold a workspace in this directory.
The agent reads install.md, runs the install, scaffolds your workspace, verifies with roster doctor, and tells you the next command.
mkdir my-team && cd my-team
npx @firatcand/roster init my-team # scaffold workspace (config/, guidelines/, function dirs)
npx @firatcand/roster install # NOW install — defaults to project scope inside a workspace
$EDITOR config/project.yaml # fill workspace identity (stage, audience, motion)
$EDITOR guidelines/voice.md # plus messaging.md, brand-book.md, icps/<persona>.md
cp templates/env.example .env # then chmod 600 .env and fill secrets
claude # or `codex`, or open Cursor
/chief-of-staff create-agent gtm sdrroster install lands skills + agents under <workspace>/.claude/, <workspace>/.codex/, and/or <workspace>/.gemini/ — workspace-local, self-contained, no cross-project pollution. The guided dialogue then reads your config/project.yaml + guidelines/ and interviews you for the gaps a stub can't fill — subagents, tools, plan names, failure modes — then writes a populated agent.md. Worked example in docs/HOWTO.md.
| Command | What it does |
|---|---|
roster install |
Install skills + agents into detected AI tools (idempotent) |
roster init |
Scaffold an agent-team workspace in CWD |
roster doctor |
Audit installation; exits non-zero on drift |
roster schedule validate |
Validate every roster/<function>/schedules.yaml |
roster schedule install |
Install a schedule into your host tool's native scheduler |
roster review [function] |
Walk pending HITL items interactively (approve / reject / defer) |
roster hooks install |
Wire SessionStart banners so chat sessions surface pending counts |
Full subcommand reference in docs/HOWTO.md. Scheduling rules, UI hand-off, and platform matrix in docs/SCHEDULING.md.
Roster scaffolds an opinionated function → agent → plan tree. Functions are top-level domains (gtm/, product/, design/, ops/). Each function holds named agents (gtm/sdr/, design/critic/). Each agent has named YAML plans — the schedulable, auditable workflow recipes.
The opinion that keeps it useful at week 12 is substrate vs artifacts: long-lived context (voice, ICPs, messaging, brand) lives at the workspace root in guidelines/. Daily tactical output (emails, posts, PR comments) lands in <function>/<agent>/logs/runs/; anything that needs human approval first lands in <agent>/pending/. Experts shape substrate. Agents produce artifacts. Don't conflate them.
A nightly reinforcement pass (the dreamer skill) reads runs + feedback, detects recurring patterns, and proposes lessons to the agent that produced them. You approve before anything is written. Quality compounds.
| Tool | Status | Project-scope skills | User-scope skills |
|---|---|---|---|
| Claude Code | Supported | <workspace>/.claude/skills/<skill>/ |
~/.claude/skills/<skill>/ |
| Codex CLI | Supported | <workspace>/.codex/skills/<skill>/ |
~/.codex/skills/<skill>/ |
| Gemini CLI | Supported | <workspace>/.gemini/extensions/<skill>/ |
~/.gemini/extensions/<skill>/ |
| Cursor | On the roadmap | — | — |
Agents land in the matching agents/ sibling of the skills dir for each tool. Project scope (default inside a roster workspace) keeps everything self-contained; user scope writes to your home directory and is visible to every project on the machine. roster doctor warns when the same skill name exists at both scopes — the user-scope copy wins, silently shadowing the workspace one.
Detection is presence-only — roster considers a tool installed if its config root exists. Override via ROSTER_CLAUDE_HOME / ROSTER_CODEX_HOME / ROSTER_GEMINI_HOME (used by the test suite).
- No
preinstall/install/postinstallscripts.npm install -g @firatcand/rosterwrites files and stops. Asserted intest/security.test.ts. - No telemetry. Nothing is collected — no analytics, no error reporting, no usage pings. Any future telemetry will be opt-in, gated behind a flag, and disclosed here before the release that introduces it.
- npm provenance. Releases are signed via
npm publish --provenancefrom GitHub Actions on tag push. Verify withnpm info @firatcand/roster dist.integrityor the provenance badge on the npm page. - Path-traversal guards on
install/initaudited under ROS-30 — regression suite intest/security.test.ts.
- docs/HOWTO.md — install, init, create-agent, run a plan, audit
- docs/ARCHITECTURE.md — substrate-vs-artifacts, lessons protocol, reinforcement loop
- docs/SCHEDULING.md — schedule install/validate, UI hand-off, Codex subagent workaround, subscription-billing rules
- docs/API.md — every script, config schema, convention
- docs/roadmap.md — what's shipped, what's next
Bug reports, fixes, and docs improvements welcome. Read CONTRIBUTING.md for the development setup, PR process, release pipeline, and the CI gates a PR has to clear. Contributors working on the CLI itself should also read CLAUDE.md for build/test/layout conventions.
MIT. See LICENSE.
Built on top of Claude Code, Codex CLI, and the broader AI-coding-tool ecosystem.