██████╗ ██████╗ ██╗ ██╗
██╔══██╗██╔═══██╗██║ ██║
██████╔╝██║ ██║██║ ██║
██╔══██╗██║ ██║██║ ██║
██║ ██║╚██████╔╝███████╗███████╗
╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚══════╝
Roll — a CLI that lets AI agents pick up backlog items and ship them through your normal git + CI workflow. Works with Claude, Cursor, Codex, Kimi, and others.
npm install -g @seanyao/roll
roll setupRequirements: bash 4+, Node.js 16+.
cd your-project
roll init # set up Roll here
roll loop on # let AI work through the backlog (optional)roll init detects legacy code and routes you to $roll-onboard when appropriate.
| Command | Description |
|---|---|
| Autonomy · daily use | |
roll loop <on|off|now|status|monitor> |
Manage the autonomous BACKLOG executor |
roll brief |
Show latest owner brief |
roll backlog [block|defer|lint|…] |
View and manage pending tasks |
roll peer |
Cross-agent negotiation & review |
roll alert |
View / clear loop alerts |
| Project · per repo | |
roll init |
Set up Roll in this project |
roll status |
Show current state and drift |
roll agent [use <name>] |
Per-project agent selection |
roll ci [--wait] |
Show or wait for current commit's CI status |
roll release |
Run the release script (human-only) |
roll review-pr <number> |
AI-powered code review for a PR |
| Machine · global | |
roll setup [-f] |
First-time install or re-sync conventions to all AI clients |
roll update |
Upgrade to latest + re-sync |
roll version |
Print installed roll version |
| Topic | English | 中文 |
|---|---|---|
| Overview & architecture | guide/en/overview.md | guide/zh/overview.md |
| Engineering methodology | guide/en/methodology.md | guide/zh/methodology.md |
| Loop (autonomous executor) | guide/en/loop.md | guide/zh/loop.md |
| Dream (nightly health scan) | guide/en/dream.md | guide/zh/dream.md |
| Peer (cross-agent review) | guide/en/peer.md | guide/zh/peer.md |
| Configuration (env vars) | guide/en/configuration.md | guide/zh/configuration.md |
| Skill selection guide | guide/en/skills.md | guide/zh/skills.md |
| Slides (deck generator) | guide/en/slides.md | guide/zh/slides.md |
| FAQ (troubleshooting) | guide/en/faq.md | guide/zh/faq.md |
| Adoption patterns | guide/en/patterns/ | guide/zh/patterns/ |
See CONTRIBUTING.md for the development workflow, test setup, and PR conventions.
See SECURITY.md. Please report vulnerabilities privately, not through public issues.
- khazix-skills by Digital Life Khazix — HV Analysis framework used by
$roll-research, MIT License. - superpowers by Jesse Vincent — composable skills library that inspired several Roll workflow patterns.