--- slug: "pi-crew" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/baphuongna/pi-crew@main/README.md" repo: "https://github.com/baphuongna/pi-crew" source_file: "README.md" branch: "main" --- # pi-crew > ## ⚠️ IMPORTANT — Read before using > > **pi-crew is a sub-agent orchestration layer that was developed almost entirely > by AI, for the author's own workflow.** It is **not** a hardened, audited > product. Here's the honest framing: > > - **AI-generated code, limited human review.** The vast majority of pi-crew > was written and iterated on by autonomous AI agents. While every change > goes through static review + runtime tests, I (the author) have not > line-by-line verified everything. There will be bugs, edge cases, and > behaviors I haven't anticipated. > - **It can spawn processes, run shell commands, and write files on your > behalf.** Dynamic workflows (`.dwf.ts`) and goal loops run with the same > privileges as your Pi session — treat any `.dwf.ts` like `node script.js` > you downloaded from the internet. > - **Built for *my* needs, not yours.** This scratches a personal itch. It > likely won't fit every workflow, team setup, or risk tolerance — and > that's fine. > > **If that sounds too risky, don't use it** — no hard feelings. > > **If you still want to use it**, the safest path is to **fork it, read the > parts you'll touch, and adapt it to your own setup.** If you find a bug, > a footgun, or a sharp edge, please open an issue or send a note — your > feedback is genuinely appreciated. Thanks. ✌️ > > See also: [SECURITY-ISSUES.md](https://github.com/baphuongna/pi-crew/blob/HEAD/SECURITY-ISSUES.md), > [docs/dynamic-workflows.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/dynamic-workflows.md#security-model-important) > (trust model), and the [Known limitations](#known-limitations) section below. **Coordinate AI agent teams inside [Pi](https://github.com/nicekate/pi-coding-agent).** pi-crew is a Pi extension that orchestrates autonomous multi-agent workflows — research, implementation, review, testing, and more — with durable state, parallel execution, worktree isolation, and safe defaults. ```text npm: pi-crew repo: https://github.com/baphuongna/pi-crew ``` ## Features - **Workflow topology advisory** (v0.9.15) — before each run, pi-crew classifies the workflow's shape (`single` / `sequential` / `concurrent` / `complex-dag`) and prints an **advisory note** with measured cost evidence (e.g. "3-step sequential: measured 5.7× slower than 3 raw Agent calls — proceeding anyway"). Never blocks — the agent decides. Tool description and prompt-snippet carry the same guidance up-front, so agents know the trade-off before calling. New files: `src/workflows/topology-analyzer.ts`, `src/workflows/preflight-validator.ts`. See [Workflow topology advisory](#workflow-topology-advisory) below. - **One Pi tool** — `team` handles routing, planning, execution, review, and cleanup - **Autonomous delegation** — policy injection decides when/how to delegate based on task complexity - **needs_attention status** — tasks that complete without calling `submit_result` get `needs_attention` (terminal) instead of `completed`; allows retry/re-run without blocking downstream phases - **Real child Pi workers** — each task spawns a separate Pi process by default; scaffold/dry-run opt-out - **Adaptive planning** — implementation workflow lets a planner agent decide subagent fanout - **Parallel execution** — tasks in the same phase run concurrently with configurable concurrency - **Durable state** — manifest, tasks, events, artifacts all persisted to disk - **Async/background runs** — detached runs survive session switches with completion notifications - **Worktree isolation** — opt-in git worktrees per task for safe parallel edits - **Rich UI** — live widget, dashboard, progress tracking, model/token display - **Observability** — metrics registry, Prometheus/OTLP exporters, heartbeat watching, deadletter queue - **Resource management** — create/update/delete agents, teams, workflows with validation - **Import/export** — portable run bundles for sharing and archiving - **Adaptive plan fanout** — single `assess` step lets a planner pick the smallest effective crew - **Adaptive workflows** — `implementation`, `review`, `parallel-research`, `research` workflows ship in `workflows/` - **Hardened secrets** — linear-time detection covers PEM keys, Authorization headers, Bearer tokens, and `key=value` patterns - **Scheduled runs** — `schedule`/`scheduled` actions with cron, interval, and one-shot support; spawned runs tracked and auto-cancelled on job removal - **Plugin system** — framework-aware context injection (Next.js, Vite, Vitest) via plugin registry - **Health scoring** — penalty-based run health with time-series snapshots - **Autonomous goal loops** (P0/P1) — `team action='goal'` runs an autonomous multi-turn loop: a worker does a turn, a separate LLM judge evaluates the transcript+evidence against the goal, and on "not-achieved" the reason is fed into the next turn's prompt. Stops on achieved / maxTurns / budget / blocked. Claude-Code-style `/goal`. See `docs/goals.md`. - **Dynamic workflows** (P2/P3) — author orchestration as a `.dwf.ts` script (JS loops/branch/cross-review) instead of a static step list. The script runs in the background, calls subagents via `ctx.agent()`/`ctx.fanOut()`, holds intermediate results in JS variables, and only `ctx.setResult()` reaches the main context. `ctx.phase()` marks logical phases; **round-14** adds `ctx.log()` (durable `dwf.log` events), `ctx.budget` (per-workflow token budget that auto-rejects `ctx.agent()` when exhausted), and `ctx.args()` (typed workflow arguments). TypeScript IntelliSense is available via `import type { WorkflowCtx } from "pi-crew/workflow"`. `workflow-create`/`-delete`/`-save` require `confirm:true` at the tool-call layer (the only gate — a malicious agent that passes `confirm:true` programmatically bypasses it; this is postinstall-equivalent trust, not a human-in-the-loop dialog). See `docs/dynamic-workflows.md`. - **Strict SKILL.md validation** (L3, v0.9.8) — skills with malformed frontmatter (missing/malformed `name`/`description`, type mismatches) now **fail-fast at discovery** with visible diagnostics, instead of silently producing broken behavior at runtime. HYBRID policy: HARD on required fields, SOFT (warn) on unknown props for forward-compat. Surfaced via `buildSkillValidationDiagnostics()`. - **Durable event replay** (L1, v0.9.8) — `RunEventBus.onWithReplay()` catches up a re-subscribing dashboard/overlay with events it missed during transient absence (toggle, reconnect), replaying from the durable JSONL log with seq-based dedup. No information loss even if the live subscriber was briefly gone. - **Lossless-by-default output handling** (L4, v0.9.8) — worker output thresholds sized from measured data (100% of real outputs fit without compaction); when compaction is unavoidable it keeps head+tail (preserves closing code fences/headings) instead of head-only truncation. No more `[pi-crew compacted N chars]` markers eating the end of a worker's result. --- ## Install ```bash pi install npm:pi-crew ``` Local development: ```bash pi install ./pi-crew ``` Post-install config bootstrap: ```bash pi-crew # after npm install node ./pi-crew/install.mjs # from local clone ``` > **Split-scope install note (v0.8.11+):** pi installs extensions under > `~/.pi/agent/npm/node_modules//`, separate from pi's own > node_modules tree (nvm / `%APPDATA%\npm` / Volta / fnm). Since v0.8.11 > pi-crew resolves the `@earendil-works/pi-coding-agent` peer dep robustly > across these layouts — no symlink/NODE_PATH workaround needed. If you ever > do hit `Cannot find module '@earendil-works/pi-coding-agent'`, set > `PI_CREW_PEER_DEP_DIR=` as a > one-line workaround (or install pi-crew in pi's own scope: > `npm install -g @earendil-works/pi-crew`). ### Uninstall `pi uninstall npm:pi-crew` removes the package, but pi doesn't fire an extension uninstall hook, so several things pi-crew created are left behind. Reverse them explicitly with `team action=cleanup`. There are **two scopes**: > **v0.8.14+**: `team action=init` **no longer injects a guidance block into > AGENTS.md** (it was redundant — the `team` tool self-describes via its tool > registration, so the agent learns pi-crew's commands from there, not AGENTS.md). > The cleanup steps below still work for removing blocks injected by **older > versions** (<0.8.14). #### Project scope (reverse `team action=init`) ```bash # 1. (Optional) Preview what would be removed, without writing: team action=cleanup dryRun=true # 2. Remove the AGENTS.md guidance block only (.crew/ preserved): team action=cleanup # 3. Remove BOTH the guidance block AND the .crew/ state directory (force): team action=cleanup force=true ``` The guidance block is wrapped in `` / `` markers, so cleanup removes **only** that block — your own AGENTS.md content is never touched. The `.crew/` directory is removed **only** with `force=true` (it's irreversible). #### User scope (remove user-level state `pi uninstall` leaves behind) ```bash # 4. Preview + remove pi-crew user-scope junk: team action=cleanup scope=user dryRun=true # preview team action=cleanup scope=user # remove ~/.pi/agent/extensions/pi-crew/ # + pi-crew smoke-test *.bak files # 5. (Optional) Also remove the global config (holds your settings): team action=cleanup scope=user force=true # also removes ~/.pi/agent/pi-crew.json ``` This removes the pi-crew state dir (`~/.pi/agent/extensions/pi-crew/`, which holds run artifacts + state), the global config (with `force=true`), and the `*.md.bak-` smoke-test backup files pi-crew's own tests may leave in `~/.pi/agent/agents/`. **Your authored agent files (`*.md`) are never touched** — pi-crew can't tell which were user-created vs test-copied, so only the clearly-pi-crew `.bak-*` backups are removed. #### Final step ```bash # 6. Remove the package itself: pi uninstall npm:pi-crew ``` --- ## Quick Start ### 1. Initialize project ```text /team-init ``` ### 2. Run a team ```text /team-run Investigate failing tests and propose a fix ``` Or via tool call: ```json { "action": "run", "team": "default", "goal": "Investigate failing tests and propose a fix" } ``` ### 3. Check status ```text /team-status /team-dashboard ``` ### 4. Get a recommendation When unsure which team/workflow fits: ```json { "action": "recommend", "goal": "Refactor auth flow and add tests" } ``` --- ## Builtin Teams | Team | Workflow | Purpose | |------|----------|----------| | `default` | explore → plan → execute → verify | Balanced, general-purpose | | `fast-fix` | explore → execute → verify | Quick bug fixes | | `implementation` | Adaptive planner decides fanout | Multi-file implementation | | `review` | explore → code-review → security-review → verify | Code review + security audit | | `research` | explore → analyze → write | Research and documentation | | `parallel-research` | Parallel shards → synthesize → write | Multi-source research | --- ## Workflow topology advisory Before every `team action='run'`, pi-crew classifies the workflow shape and prints an informational note. **It never blocks** — agents decide whether to proceed, refactor, or override. ### How it works ```text team action='run', workflow='fast-fix', goal='...' ↓ pi-crew analyzes topology: 3-step sequential ↓ ⚠️ [team-tool.preflight] WARN: 3-step sequential chain: measured 5.7× slower and 1.9× costlier than 3 raw Agent calls (Run #3 in .crew/state/runs/). Proceeding anyway. ↓ Workflow runs to completion. Agent sees the note, decides for next time. ``` ### Topology → advisory level | Topology | When | Level | What pi-crew prints | |---|---|---|---| | `single` | 1 step, no concurrency | `warn` | "raw Agent tool would be ~30× faster and ~5× cheaper. Proceeding anyway." | | `sequential` (2-3 steps) | Linear chain, no fan-out | `warn` | "measured 5.7× slower than raw Agent calls. Proceeding anyway." | | `sequential` (4+ steps) | Linear chain, longer | `warn` | "audit trail may justify pi-crew overhead. Proceeding anyway." | | `concurrent` | ≥3 truly parallel agents (parallelGroup) | `note` | "✅ Validated use case: N-way parallel fan-out. pi-crew's parallelism wins." | | `complex-dag` | 4+ steps with data dependencies | `note` | "✅ Validated use case: complex DAG with adaptive plan." | | `dynamic` | `.dwf.ts` script | `info` | "Runtime decides topology." | ### When to prefer raw `Agent` over `team` Use the raw `Agent` tool when: - You have a single task or quick question (1-step) - You have 2–3 sequential independent steps (no DAG branching, no concurrency) Use `team` when: - You have ≥3 agents running TRULY CONCURRENTLY (`parallelGroup`) - You have a COMPLEX DAG (4+ steps with data dependencies, branching) - You need an audit trail, team coordination, or worktree isolation that justifies pi-crew's overhead ### How agents learn the rule The guidance is available in three places agents see: 1. **`team` tool description** — the LLM reads this when considering whether to call the tool. Includes an explicit "ℹ️ ADVISORY NOTE (preflight, never blocks)" section. 2. **`team` prompt snippet** — rendered in agent context when the tool is relevant. Single-line summary of the rule. 3. **`.crew/knowledge.md` CONVENTIONS section** — always injected into every worker session's context. Contains the full 4-question self-check. ### How to silence the advisory The advisory is **informational only** — there is no `force:true` flag needed (the run proceeds regardless). If you want to silence the `console.warn` output for cleaner logs, set `PI_CREW_QUIET_PREFLIGHT=1` in your environment. ### Implementation - `src/workflows/topology-analyzer.ts` — pure classifier (parses workflow YAML, builds DAG, detects parallelGroups) - `src/workflows/preflight-validator.ts` — returns `{level: info|note|warn, message, suggestion}` (never throws) - Integration: `src/extension/team-tool/run.ts` (extension layer, prints advisory) + `src/runtime/team-runner.ts` (defense-in-depth, also logs) ### Tests - `test/unit/topology-analyzer.test.ts` — 13 cases (each topology + edge cases) - `test/unit/preflight-validator.test.ts` — 11 cases (each level + advisory contract) - `test/functional/pi-crew-live.test.ts` + `test/functional/pi-crew-live-broad.test.ts` — 16 live integration tests run against the **real pi binary + real LLM provider** (verified after v0.9.42 audit, ~26 commits). Use these when you want to confirm end-to-end behavior, not just unit-level invariants. ## Recent changes ### v0.9.45 – v0.9.46 (2026-07-20): security + perf remediation, UI stability - **Custom agent roles default to read-only (FIND-12, breaking):** `permissionForRole()` returns `"read_only"` for unknown roles (was permissive `"workspace_write"`). Write-capable roles are now an explicit allowlist (`WRITE_ROLES`). See `CHANGELOG.md` for the migration. - **Mailbox / snapshot-cache / scan perf:** delivery cache + async append (FIND-01/02), `listActive` TTL + mtime-sort strict limit (FIND-03/04), byte-bounded event-log tail-read (FIND-05). - **Heartbeat race (FIND-06):** in-flight guard + drain + terminal-safety + late-save repair in the coalesced task group. - **UI flicker eliminated:** the render path no longer hard-deletes snapshot entries, so the crew widget / powerbar / live sidebar stay stable (no more "(loading…)" flashing every ~160ms). - **Emoji width-overflow crash fixed for good:** `visibleWidth` delegates to pi-tui's own measure, so agent-output emoji can never exceed terminal width. - **Background-subagent notifications coalesce:** N near-simultaneous completions now produce ONE consolidated wake-up instead of N drips. ### v0.9.42 – v0.9.44: 4-wave audit + flaky-CI fixes A 4-wave audit + fix pass was completed (see `UPGRADE_REVIEW.md` for the full 647-line report and `CHANGELOG.md` for the diff): - **−481 KB** bundle size (externalized `acorn` + fixed `@sinclair/typebox` name). - **−31.1%** in `child-pi.ts` (1842 → 1270 lines via 6 decomposition steps). - **~30 bug fixes** across security, correctness, budget enforcement, worker cap, observability, and worktree isolation. - **Lock re-entrance guard** via `AsyncLocalStorage` (H-1) — fixes a root-cause mutual-exclusion violation. - **Task-level metrics now functional** (OBS-NEW-1/2) — `crew.task.{count,duration_ms,tokens_total}` were always zero; now emit on every run completion. - **Live-test-only bugs found** (mock tests had passed): token usage not captured (nested `obj.message.usage`), child-pi spawning wrong binary (`argv1` trust heuristic), worktree mode blocked by own `.gitignore`. ## Builtin Agents ``` analyst · critic · executor · explorer · planner · reviewer security-reviewer · test-engineer · verifier · writer ``` --- ## Runtime Modes pi-crew supports multiple runtime modes for task execution: | Mode | Description | |------|-------------| | `auto` (default) | Uses `child-process` unless overridden by config | | `child-process` | Spawns real `pi` child processes — each task runs in isolation | | `scaffold` | Dry-run mode — renders prompts and persists artifacts without executing | | `live-session` (experimental) | In-process session execution within the parent Pi | ```json // Use scaffold mode (no real workers, just prompts) { "action": "run", "team": "default", "goal": "...", "runtime": { "mode": "scaffold" } } // Disable workers globally { "executeWorkers": false } ``` ## Async Runs Async runs are **detached** from the session — they survive session switches and reloads. Pi-crew notifies when complete. ```json { "action": "run", "team": "default", "goal": "...", "async": true } ``` ```text /team-run --async Investigate failing tests ``` Background runs use `node --import jiti-register.mjs` for TypeScript support. See [docs/runtime-flow.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/runtime-flow.md) for details. ## Worktree Isolation Worktree mode creates an **isolated git worktree per task** — safe for parallel edits to the same branch. ```json { "action": "run", "team": "implementation", "goal": "Refactor auth", "workspaceMode": "worktree" } ``` ```text /team-run --worktree Refactor auth ``` Requirements: - Git repository (cwd must be inside a git repo) - Clean working tree (no uncommitted changes in the leader worktree) - Can be disabled via config: `requireCleanWorktreeLeader: false` - Worktrees auto-cleanup on run completion/cancel If preconditions are not met, a friendly error message is returned instead of crashing. --- ## Configuration ### Config Paths | Scope | Path | |-------|------| | User (primary) | `~/.pi/agent/pi-crew.json` | | User (legacy, still read for migration) | `~/.pi/agent/extensions/pi-crew/config.json` | | Project (crewRoot) | `.crew/config.json` (or `.pi/teams/config.json` legacy) | | Project (alt) | `.pi/pi-crew.json` | ### Quick Config ```text /team-config # view all settings /team-config runtime.mode=scaffold # set a key (--project for project scope) /team-config --unset=runtime.mode # reset a key to default /team-config --project runtime.mode # project-scoped view /team-settings path # show config file path ``` ### Key Settings | Section | Keys | Default | |---------|------|---------| | **Runtime** | `mode`: `auto` \| `child-process` \| `scaffold` \| `live-session` | `auto` | | | `maxTurns`, `graceTurns`, `groupJoin`, `requirePlanApproval` | various | | **Concurrency** | `limits.maxConcurrentWorkers` | workflow-dependent | | | `limits.maxTaskDepth`, `limits.maxChildrenPerTask` | 2, 5 | | **Async** | `asyncByDefault` | `false` | | | `runtime.groupJoin`: `off` \| `group` \| `smart` | `smart` | | **Autonomy** | `profile`: `manual` \| `suggested` \| `assisted` \| `aggressive` | `suggested` | | | `autonomous.injectPolicy`, `preferAsyncForLongTasks` | true, false | | **UI** | `widgetPlacement`, `dashboardPlacement` | compact widget | | | `showModel`, `showTokens` | display controls | | **Reliability** | `autoRetry`, `autoRecover`, `deadletterThreshold` | opt-in | | **Observability** | `observability.enabled`, `observability.pollIntervalMs`, `otlp.enabled`/`otlp.endpoint` | opt-in | | **Worktree** | `worktree.setupHook`, `worktree.linkNodeModules`, `worktree.seedPaths` (mode is set via `workspaceMode: "worktree"` at run time) | disabled by default | > ⚠️ **Trust boundary**: project config cannot override sensitive execution controls (workers, runtime mode, autonomy, agent overrides). Set those in **user config** only. 📖 Full config reference: [docs/commands-reference.md#team-settings--config-management](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/commands-reference.md) and [schema.json](https://github.com/baphuongna/pi-crew/blob/HEAD/schema.json) --- ## Reliability & Trust ### Compaction resilience pi-crew survives Pi's context compaction. When the context is compacted (auto or manual), in-flight crew runs are detected and a **resume directive** is injected into the post-compaction context, so tasks continue instead of stalling. You'll see a notification like: ``` Context compacted. 1 pi-crew run(s) still in-flight — use team status to continue. ``` **Durable event replay** (v0.9.8, L1): even if a dashboard/overlay is briefly gone during compaction or a reconnect, `RunEventBus.onWithReplay()` catches it up with the events it missed, replaying from the durable JSONL log with seq-based dedup — no information loss. (The dashboard wires this up per-run; the primitive is available for any subscriber.) **Lossless-by-default worker output** (v0.9.8, L4): output-handling thresholds are sized from measured real data (100% of real worker outputs fit without any compaction). When compaction *is* unavoidable, it keeps head+tail instead of head-only truncation, so closing code fences and headings survive — no more `[pi-crew compacted N chars]` markers eating the end of a result. ### Plan-level human-in-the-loop (HITL) Set `runtime.requirePlanApproval = true` to gate **any workflow** at the plan→execute boundary. After the read-only (planning) phases complete, the run pauses for explicit approval before mutating tasks run: ``` team api op=approve-plan runId= # approve → execute team api op=cancel-plan runId= # cancel ``` This is plan-level (not per-step) — per-step gates would kill the parallelism that's pi-crew's point. ### Cross-run memory (`.crew/knowledge.md`) Create `.crew/knowledge.md` in your project root with durable learnings (code style, test commands, common pitfalls, past refactors). It's auto-read (up to 16KB) and injected into **every** agent's system prompt — the main session and each crew worker. pi-crew gets better the longer you use it. ```markdown # Project Knowledge - Tests: run with `npm test` (not jest directly) - Style: tabs, not spaces - Auth refactor (2026-06): split auth.ts into session.ts + api.ts ``` ### Cost visibility Every `team summary ` includes a per-role cost report: ``` ═══ Cost Report ═══ Tokens: 134k (in 112k, out 5.7k, cache-write 16k) Cost: $0.7700 across 18 turn(s) By role: executor (2 tasks): $0.6100 — 79%, 98k tok, 13 turns reviewer (1 task): $0.1100 — 14%, 23k tok, 3 turns ``` ### Single-agent mode (cliff hedge) Any workflow can run single-agent instead of multi-agent — composing all phases into one sequential prompt: ``` team plan team=default workflow=default goal="..." singleAgent=true ``` This is pi-crew's cliff-resilient mode: the workflow definitions, phase structure, and artifact contracts survive even if a single large-context model outperforms multi-agent teams. --- ## Tool Actions ```json // Execute workflow (foreground or async) { "action": "run", "team": "default", "goal": "..." } { "action": "run", "team": "default", "goal": "...", "async": true } // Monitor & control { "action": "status", "runId": "team_..." } { "action": "summary", "runId": "team_..." } { "action": "events", "runId": "team_..." } { "action": "artifacts", "runId": "team_..." } { "action": "cancel", "runId": "team_..." } { "action": "resume", "runId": "team_..." } { "action": "retry", "runId": "team_..." } { "action": "steer", "runId": "team_...", "taskId": "01_explore", "message": "Focus on src/ only" } { "action": "respond", "runId": "team_...", "message": "Answer" } { "action": "wait", "runId": "team_..." } // Discovery { "action": "list" } { "action": "get", "resource": "team", "team": "default" } { "action": "get", "resource": "agent", "agent": "explorer" } { "action": "get", "resource": "workflow", "workflow": "review" } { "action": "recommend", "goal": "Refactor auth flow" } { "action": "search", "goal": "heartbeat detection" } // Resource management { "action": "create", "resource": "agent", "config": { "name": "api-reviewer", ... } } { "action": "update", "resource": "team", "name": "backend", "config": { ... } } { "action": "delete", "resource": "workflow", "name": "quick-review" } { "action": "validate" } // Run maintenance { "action": "cleanup", "runId": "team_..." } { "action": "forget", "runId": "team_...", "confirm": true } { "action": "prune", "olderThanDays": 7, "confirm": true } { "action": "export", "runId": "team_..." } { "action": "import", "path": "/path/to/bundle.tar.gz" } // Environment & configuration { "action": "doctor", "config": { "smokeChildPi": true } } { "action": "config" } { "action": "init", "config": { "copyBuiltins": true } } { "action": "autonomy", "profile": "assisted" } // Advanced { "action": "api", "runId": "team_...", "config": { "operation": "read-manifest" } } { "action": "plan", "team": "default", "goal": "..." } { "action": "orchestrate", "planPath": "plan.md", "team": "implementation", "goal": "..." } { "action": "parallel", "config": { "tasks": [{"goal": "...", "agent": "explorer"}] } } { "action": "worktrees", "runId": "team_..." } { "action": "graph", "runId": "team_..." } { "action": "explain", "runId": "team_..." } { "action": "health" } { "action": "doctor" } { "action": "cache" } { "action": "invalidate", "runId": "team_..." } // Scheduled runs { "action": "schedule", "team": "fast-fix", "goal": "Run tests", "cron": "0 9 * * MON" } { "action": "schedule", "team": "default", "goal": "...", "interval": 3600000 } { "action": "schedule", "team": "research", "goal": "...", "once": "+10m" } { "action": "scheduled" } // Diagnostics & settings { "action": "config" } { "action": "settings" } { "action": "autonomy" } { "action": "anchor" } { "action": "onboard" } { "action": "auto-summarize" } ``` 📖 Full actions reference (40+ actions): [docs/actions-reference.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/actions-reference.md) --- ## Slash Commands ```text /team-run [--team=X] [--async] [--worktree] /team-status /team-dashboard /team-doctor /team-init [--copy-builtins] /team-config [key=value] /team-autonomy [status|on|off|suggested|assisted] ``` 📖 Full commands reference: [docs/commands-reference.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/commands-reference.md) --- ## Resource Discovery Agents, teams, and workflows are discovered from three layers: ``` builtin (package) < user (~/.pi/agent/) < project (.crew/ or .pi/teams/) ``` Project resources can add new names but **cannot shadow** builtin/user resources. ### Resource Paths | Type | Builtin | User | Project | |------|---------|------|---------| | Agent | `agents/*.md` | `~/.pi/agent/agents/*.md` | `.crew/agents/*.md` | | Team | `teams/*.team.md` | `~/.pi/agent/teams/*.team.md` | `.crew/teams/*.team.md` | | Workflow | `workflows/*.workflow.md` | `~/.pi/agent/workflows/*.workflow.md` | `.crew/workflows/*.workflow.md` | ### Custom Resources with Routing Metadata ```yaml --- name: api-reviewer description: Reviews API changes triggers: api, endpoint, contract useWhen: backend API changes, OpenAPI changes avoidWhen: docs-only edits cost: cheap category: backend --- Your system prompt here. ``` 📖 Full resource formats: [docs/resource-formats.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/resource-formats.md) --- ## State Layout ``` / # .crew/ (new) or .pi/teams/ (legacy) ├── state/runs/{runId}/ │ ├── manifest.json # run metadata │ ├── tasks.json # task graph + status │ ├── events.jsonl # append-only events │ └── agents/{taskId}/status.json # per-agent state ├── artifacts/{runId}/ │ ├── goal.md │ ├── prompts/{taskId}.md │ ├── results/{taskId}.txt │ ├── logs/{taskId}.log │ └── summary.md ├── worktrees/{runId}/{taskId}/ └── imports/{runId}/run-export.json ``` --- ## Environment Variables | Variable | Purpose | |----------|---------| | `PI_CREW_USE_BUNDLE=1` | Load via bundled `dist/index.mjs` (~5% faster cold-start). Default: strip-types. Requires `npm run build:bundle` to have produced `dist/`. Falls back to strip-types with a one-time warning if the bundle is missing. See `scripts/bench-cold-start.mjs`. | | `PI_CREW_EXECUTE_WORKERS=0` | Disable child workers (scaffold mode) | | `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy disable flag | | `PI_TEAMS_MOCK_CHILD_PI=success` | Mock child worker for testing | | `PI_TEAMS_PI_BIN=` | Explicit Pi CLI path | | `PI_TEAMS_HOME=` | Override home for tests | --- ## Development ### Auto-rebuild bundle on edit For active development on the bundle, run the watcher in a separate terminal: ```bash npm run watch:bundle ``` This watches `src/` + `index.bundle.ts` and rebuilds `dist/index.mjs` after a 300ms debounce. Zero added dependencies (uses native `node:fs.watch` with per-directory watchers). ```bash npm run watch:bundle # watch + auto-rebuild npm run watch:bundle --debounce 500 # custom debounce node scripts/watch-bundle.mjs --once # build once and exit (CI prep) ``` The watcher is the dev-loop companion to `check:bundle-staleness` (CI gate) — together they eliminate the "edit src/foo.ts, forget to rebuild, run stale bundle" failure mode. ```bash cd pi-crew npm install # dependencies npm test # unit + integration tests (~4,800 tests) npm run typecheck # tsc --noEmit npm run ci # full CI-equivalent check npm pack --dry-run # package verification ``` Stats: **431 source files** (87K lines) · **606 test files** (85K lines) · **~5,860 tests, 0 failures** · **CI: Ubuntu ✅ macOS ✅ Windows ✅** --- ## Documentation | Doc | Contents | |-----|----------| | [docs/actions-reference.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/actions-reference.md) | Full tool actions + examples | | [docs/commands-reference.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/commands-reference.md) | Slash commands + `/team-api` | | [docs/resource-formats.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/resource-formats.md) | Agent/team/workflow file formats | | [docs/usage.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/usage.md) | Usage patterns + config examples | | [docs/troubleshooting.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/troubleshooting.md) | Common errors, recovery, and error-code reference (E001–E012) | | [docs/architecture.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/architecture.md) | Internal architecture + run flow | | [docs/runtime-flow.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/runtime-flow.md) | Runtime execution details | | [docs/goals.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/goals.md) | **v0.9.0** Autonomous goal loops (`team action='goal'`) | | [docs/dynamic-workflows.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/dynamic-workflows.md) | **v0.9.0** `.dwf.ts` script runtime + trust model | | [docs/live-mailbox-runtime.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/live-mailbox-runtime.md) | Mailbox + live-session runtime | | [docs/publishing.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/publishing.md) | Release & publish process | | [docs/next-upgrade-roadmap.md](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/next-upgrade-roadmap.md) | Future upgrade roadmap | | [schema.json](https://github.com/baphuongna/pi-crew/blob/HEAD/schema.json) | Config JSON schema | Research docs (not in package): [`docs/pi-crew-research/`](https://github.com/baphuongna/pi-crew/tree/main/docs) — audits, deep research, distillation notes. --- ## Known limitations This is AI-developed software built for a personal workflow. These are the sharp edges I'm aware of — there are almost certainly others I'm not. - **Multi-step goal-wrap crashes non-deterministically.** Goal-wrapping multi-step builtin workflows (`fast-fix`, `default`) can hit a V8/libuv event-loop race that kills the background process with no signal, no core, and no V8 diagnostic report (8 investigation attempts: gdb, strace, perf, `--report-on-fatalerror`, sync-fs workarounds, worker-thread atomic writer — see `research-findings/goal-workflow/17-PHASE1.5-CRASH-INVESTIGATION-RFC.md`). **Mitigation:** multi-step workflows silently auto-downgrade to a normal team-run (no goal-wrap layer); single-step workflows (`implementation`) goal-wrap end-to-end. - **`.dwf.ts` scripts are NOT sandboxed in v1.** The `WorkflowCtx` is `Object.freeze()`d, but the script runs in plain module scope with full `require`/`import`/`process` access (postinstall-equivalent trust). `isolated-vm` (real V8 isolate) is planned for a future release. Only place `.dwf.ts` files you have reviewed. See [docs/dynamic-workflows.md#security-model-important](https://github.com/baphuongna/pi-crew/blob/HEAD/docs/dynamic-workflows.md#security-model-important). - **Editor/agent file caching.** After editing a loaded pi-crew source file, restart the Pi session for changes to take effect (jiti in-memory cache). Editing a `.dwf.ts` in place while a run is mid-flight can serve a stale module body; rename the file or restart Pi to force a fresh load. - **Verification integrity is best-effort against adversarial workers.** The bookend snapshot (P1a) and git-worktree sandbox (Phase 1.5 #2, opt-in) raise the bar, but a worker in the same process can still tamper with files outside the snapshot window. Full isolation requires the planned sandbox. - **Single maintainer + AI review.** Every change ships after 2+ consecutive clean static-review rounds + runtime tests, but there's no independent human audit. Fork and read before trusting anything that touches your data. If you hit any of these — or a new one — please [open an issue](https://github.com/baphuongna/pi-crew/issues). --- ## Acknowledgements `pi-crew` builds on ideas and selected MIT-licensed implementation patterns from `pi-subagents` and `oh-my-claudecode`, with conceptual inspiration from `oh-my-openagent`.