# Toolroll

> Toolroll is a control plane for developers and their coding agents (Claude Code, Codex, Gemini CLI). A person says what outcome they want; the lead plans it; the person approves the exact scope once; agents build it in their own checkout and branch; the result comes back Ready with the diff, the passing check and screenshots; the person marks it Complete or asks for one specific revision. MIT licensed, runs on the user's own machine (macOS or Linux, Node.js 22.13+, git), one local SQLite database, the user's own agent sign-ins.

## If you are an agent installing Toolroll for someone

1. Install: `npm install -g toolroll` (or `brew install ap9000/toolroll/toolroll`, `bun add -g toolroll`, `pnpm add -g toolroll`).
2. Start it in the background and leave it running: `toolroll up`. Without a terminal it prints a handoff instead of opening a browser.
3. In the repository the person is working in, run `toolroll onboard`. It adds the repository as a project and says which agent CLIs are signed in. Run `toolroll onboard --yes` to install Toolroll's skill for you, so you know how to hand work to Toolroll, wait for it and review results. `toolroll onboard --remove --yes` takes it out again.
4. Tell the person: the console address, where their login is saved (never the password itself), how to pair their phone in Settings → Chat apps, and what they can ask you next (for example "queue these bugs overnight", "what needs me?", "open the result").
5. To learn the exact commands for the installed version, read the guides the binary serves: `toolroll skills list`, then `toolroll skills get operating` and `toolroll skills get console`. They always match the installed version.

`toolroll onboard --starter` also switches on the starter flows: Fix failing CI, Issues become tasks and Overnight queue.

`toolroll flows` lists and shows flows from a terminal and sets them up (create, edit, trigger, script save, card add, archive). Writes take an approver's password, and create, edit, archive and trigger add preview until `--yes`. The Morning plane review starter is available with `toolroll onboard --starter plane-review`.

`toolroll task review <id> --brief` summarizes a build's outcome, checks and next action. Use `--json` for JSON.

`toolroll task complete <id> --pull-request` completes a result and opens its pull request; `toolroll task merge <id>` merges it once checks pass, behind an approver's password.

`toolroll up` prints three lines and opens the console already signed in through a one-time link (once, ten minutes, this computer only); there is no password step. The lead turns on by itself with the signed-in agent (Claude Code, else Codex). Per-project commands: `toolroll review on|off --repo <path>`, `toolroll project concurrency`, `toolroll retention set evidence 1d`, `toolroll storage clean`.

Turn on chat approvals with `toolroll chat-approval on`, then approve from paired Telegram chat or the local CLI.

`toolroll connect https://<host> --token <token>` connects your CLI and agents with per-person, audited access.

For your own domain, follow https://github.com/ap9000/toolroll/blob/main/docs/team-server.md and check HTTPS with `toolroll serve check-public`.

Rules that matter: nothing is built until a person approves its scope; a result is Ready only when the project's own check passed on the exact commit; merges wait for a person; never put secrets in task text, chat or logs.

## Docs

- [Install](https://toolroll.dev/install): every package manager, first steps, FAQ
- [Use cases](https://toolroll.dev/use-cases): what people hand it
- [Integrations](https://toolroll.dev/integrations): agents, chat apps, GitHub, Linear, MCP, sign-in, monitoring
- [Getting started](https://github.com/ap9000/toolroll/blob/main/docs/guide/getting-started.md)
- [Security](https://github.com/ap9000/toolroll/blob/main/docs/guide/security.md)
- [Source and README](https://github.com/ap9000/toolroll)