@vincenzoimp/pitcrew
A crew for the pi coding agent: roles instead of model names, a per-session mode, child agents you can watch and steer, a guard, a verify gate, skills, and an unattended runner.
Package details
Install @vincenzoimp/pitcrew from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@vincenzoimp/pitcrew- Package
@vincenzoimp/pitcrew- Version
0.1.2- Published
- Nov 13, 2026
- Downloads
- 699/mo · 699/wk
- Author
- vincenzoimp
- License
- MIT
- Types
- extension, skill
- Size
- 1,005.6 KB
- Dependencies
- 6 dependencies · 1 peer
Pi manifest JSON
{
"image": "https://raw.githubusercontent.com/VincenzoImp/pitcrew/main/docs/assets/screen-agents.png",
"skills": [
"./skills"
],
"prompts": [],
"extensions": [
"./extensions/roles/index.ts",
"./extensions/rules/index.ts",
"./extensions/mode/index.ts",
"./extensions/guard/index.ts",
"./extensions/verify-gate/index.ts",
"./extensions/status/index.ts",
"./extensions/context/index.ts",
"./extensions/handoff/index.ts",
"./extensions/web/index.ts",
"./extensions/agent/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
What you get
- Roles, not model names. You talk to
lead;worker,scout,reviewerandseconddo the rest. A profile says which model and thinking level answers for each role, per session. - Child agents you can see. The lead starts children in the background;
/agentsshows each one live, and you can steer it, answer it or stop it. - A mode per piece of work.
stopsays how far the agent goes alone (a plan, local commits, a PR, a merge);rigorsays which checks run. - Guard rails. The guard blocks catastrophic commands and asks before risky ones; the verify gate means "done" only when the repo's own check passed on the current tree.
- Unattended delivery.
pitcrew runtakes the issues of a milestone one by one: worktree, fresh worker, checks, PR, review, merge or stop, cleanup. Run it again to continue. - Web tools, 14 skills, and a footer with context use, cache, cost and subscription windows.
It is one pi package. It works with any provider pi supports: a subscription, an API key, or a local server.
Quick start
- Install pi and log in to a provider (
/loginin pi). - Set up pitcrew in a terminal (it asks one or two questions):
npx @vincenzoimp/pitcrew init - In a repo of yours, run
piand ask for something small: "the test for X fails, find out why and fix it".
pitcrew init checks Node and pi, registers the package, adds the baseline settings without
changing yours, proposes a profile that works with your logins, and lists the optional parts
(GitHub CLI, Exa search key, Claude bridge, Docker). Model calls are billed by your provider (your
plan, its credits, or API prices); the footer shows the cost and the plan windows. More:
getting started.
Concepts
| Concept | In one line |
|---|---|
| Role | a model slot: lead (you talk to it), worker, scout, reviewer, second |
| Profile | which model and thinking level answer for each role; examples for claude-bridge, codex, anthropic, openai, google, local; with none set, the first in this order whose models you can use |
| Session mode | stop (how far the agent goes alone) and rigor (which checks run), per session |
| Tracking | a repo setting: where plans and work items live (none, local, github) |
| Agent, child | an agent is a definition (worker, scout, reviewer, researcher); a child is one running instance |
| Skill | method for one kind of work; the model picks some, you start the others with /skill:<name> |
| Guard | blocks catastrophic commands, asks before risky ones, holds the delivery rules |
| Verify gate | "done" means the repo's own check passed on the current tree |
| Runner | pitcrew run: delivers the issues of a target unattended, resumable |
| Sandbox | the container pitcrew run uses for repos that are not yours |
Every word: glossary. Three diagrams: how it works.
Commands
| In a session | |
|---|---|
/profile, /role |
show or change the role map of this session |
/mode |
show or change stop, rigor and the switches |
/agents (alt+a) |
the panel of child agents |
/handoff [goal] |
go on in a fresh session with the same mode and roles |
/guard, /stats, /skill:<name> |
guard dialogs on or off; usage and cost; run a skill |
| In the shell | |
|---|---|
pitcrew init |
set up, or check a setup |
pitcrew run <milestone | issue | label:x> |
deliver GitHub issues unattended; pitcrew status for the digest |
pitcrew tidy |
remove the worktree and branches of merged work, with proof |
pitcrew check |
lean-code checks on a branch |
pitcrew box |
the sandbox container |
All of them, with flags and keys: commands.
What it costs
Measured once each with pi 1.5.2, so read them as orders of size. Details and models: live tests.
| Thing | Cost |
|---|---|
| Standing context: global rules and model-picked skill descriptions | about 1,300 tokens in every request |
| First request of a session | about 4,700 tokens natively; about 7,700 through the Claude bridge |
First request of a scout child |
about 2,400 tokens natively; about 4,600 through the bridge |
web_search |
Exa: about $0.012 per search (free monthly credit), no model tokens; Codex: 8,700 to 13,200 tokens of the plan |
pitcrew run, one small issue, stop pr |
about 75,000 tokens, 47 s (local model) |
code-review of a small risky change |
about 180,000 tokens sent by the lead, plus 77,000 by its children |
| Sandbox start | 1.9 s |
Limits
- Sessions are not sandboxed. Commands run as you, on this machine. The guard catches mistakes
with pattern rules; it is not a security boundary. Only
pitcrew runuses the container. - No fallback model. If a role's model is missing or refuses for quota, the request fails with
the reason; after the reset you resume (
pi --continue,/agents resume, the samepitcrew run). - Small local models overflow on large reads and research fan-out, and often do not load a skill by themselves: name it.
- Claude through
pi-claude-bridge(optional) adds Claude Code's own prompt and drops some prompt channels; pitcrew uses only the channels that pass (claude-access). pitcrew runworks one issue at a time, on GitHub only.
When something goes wrong: troubleshooting.
Docs
Getting started · Install · How it works · Commands · All docs
Contributing
Issues and pull requests are welcome: read CONTRIBUTING first. Security problems: SECURITY. Changes: CHANGELOG.
Licence
MIT. Text and code from other projects keep their licences: THIRD_PARTY_NOTICES. Versions tested against: UPSTREAM.
