239 lines
5.4 KiB
Markdown
239 lines
5.4 KiB
Markdown
# pi-crew Usage
|
|
|
|
## Config
|
|
|
|
Optional config path:
|
|
|
|
```text
|
|
~/.pi/agent/extensions/pi-crew/config.json
|
|
```
|
|
|
|
Create a default config:
|
|
|
|
```bash
|
|
node ./pi-crew/install.mjs
|
|
```
|
|
|
|
Supported fields:
|
|
|
|
```json
|
|
{
|
|
"asyncByDefault": false,
|
|
"executeWorkers": true,
|
|
"notifierIntervalMs": 5000,
|
|
"requireCleanWorktreeLeader": true,
|
|
"autonomous": {
|
|
"profile": "suggested",
|
|
"enabled": true,
|
|
"injectPolicy": true,
|
|
"preferAsyncForLongTasks": false,
|
|
"allowWorktreeSuggestion": true
|
|
},
|
|
"runtime": {
|
|
"mode": "auto",
|
|
"groupJoin": "smart",
|
|
"groupJoinAckTimeoutMs": 300000,
|
|
"completionMutationGuard": "warn",
|
|
"requirePlanApproval": false
|
|
},
|
|
"ui": {
|
|
"widgetPlacement": "aboveEditor",
|
|
"widgetMaxLines": 8,
|
|
"powerbar": true,
|
|
"dashboardPlacement": "center",
|
|
"dashboardWidth": 72,
|
|
"dashboardLiveRefreshMs": 1000,
|
|
"autoOpenDashboard": false,
|
|
"autoOpenDashboardForForegroundRuns": false,
|
|
"showModel": true,
|
|
"showTokens": true,
|
|
"showTools": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Local Pi smoke test
|
|
|
|
```bash
|
|
cd pi-crew
|
|
npm run smoke:pi
|
|
```
|
|
|
|
Then open Pi and run:
|
|
|
|
```text
|
|
/team-doctor
|
|
/team-validate
|
|
/team-autonomy status
|
|
```
|
|
|
|
## Default run: real worker execution
|
|
|
|
By default, `pi-crew` launches each task as a separate child Pi worker process. The parent Pi session orchestrates; workers execute independently and stream output to durable run state.
|
|
|
|
```json
|
|
{
|
|
"action": "run",
|
|
"team": "default",
|
|
"goal": "Implement login with tests"
|
|
}
|
|
```
|
|
|
|
## Scaffold / dry run
|
|
|
|
Use scaffold mode only when you want durable prompts/artifacts without launching child workers.
|
|
|
|
```json
|
|
{
|
|
"action": "run",
|
|
"team": "default",
|
|
"goal": "Plan only",
|
|
"config": {
|
|
"runtime": { "mode": "scaffold" }
|
|
}
|
|
}
|
|
```
|
|
|
|
## Async run
|
|
|
|
```json
|
|
{
|
|
"action": "run",
|
|
"team": "implementation",
|
|
"goal": "Refactor auth module",
|
|
"async": true
|
|
}
|
|
```
|
|
|
|
Check status:
|
|
|
|
```json
|
|
{
|
|
"action": "status",
|
|
"runId": "team_..."
|
|
}
|
|
```
|
|
|
|
Background `Agent`/`crew_agent` subagents wake the parent Pi session when they complete, so the parent can call `get_subagent_result`/`crew_agent_result` and continue without waiting for another user prompt.
|
|
|
|
## State and API safety
|
|
|
|
State paths are validated before read/write operations. Run ids, imported bundles, artifact and transcript references, mailbox files, and agent control/log files must stay inside their expected `.crew` roots and symlink escapes are rejected. Read-only mailbox APIs return default state without creating mailbox files when no messages exist.
|
|
|
|
Group-join result delivery uses the normal outbox mailbox and normal `/team-api ... ack-message`. `runtime.groupJoinAckTimeoutMs` only emits observability (`agent.group_join.ack_timeout`) and does not block run completion.
|
|
|
|
`runtime.completionMutationGuard` defaults to `warn`. Use `off` to disable or `fail` to fail implementation-style workers that complete without observed mutation tool calls.
|
|
|
|
## Worktree mode
|
|
|
|
```json
|
|
{
|
|
"action": "run",
|
|
"team": "implementation",
|
|
"goal": "Refactor API layer",
|
|
"workspaceMode": "worktree"
|
|
}
|
|
```
|
|
|
|
The leader repository must be clean. Per-task worktrees are created under the project crew root (`.crew/` for new projects, `.pi/teams/` when the repo already has `.pi/`):
|
|
|
|
```text
|
|
<crewRoot>/worktrees/{runId}/{taskId}
|
|
```
|
|
|
|
Cleanup:
|
|
|
|
```json
|
|
{
|
|
"action": "cleanup",
|
|
"runId": "team_..."
|
|
}
|
|
```
|
|
|
|
Dirty worktrees are preserved unless `force: true` is provided.
|
|
|
|
## Slash commands
|
|
|
|
```text
|
|
/teams
|
|
/team-run default "Implement login with tests"
|
|
/team-run --team=implementation --workflow=implementation --async "Refactor auth"
|
|
/team-cancel team_...
|
|
/team-run --worktree default "Change API safely"
|
|
/team-status team_...
|
|
/team-summary team_...
|
|
/team-resume team_...
|
|
/team-events team_...
|
|
/team-artifacts team_...
|
|
/team-worktrees team_...
|
|
/team-cleanup team_...
|
|
/team-forget team_... --confirm
|
|
/team-export team_...
|
|
/team-import .crew/artifacts/team_.../export/run-export.json # or .pi/teams/artifacts/... on legacy layout
|
|
/team-imports
|
|
/team-prune --keep=20 --confirm
|
|
/team-manager
|
|
/team-dashboard
|
|
/team-api team_... read-mailbox direction=outbox
|
|
/team-api team_... send-message direction=outbox taskId=task_... to=worker body="hello"
|
|
/team-api team_... validate-mailbox repair=true
|
|
/team-init
|
|
/team-init --copy-builtins
|
|
/team-config
|
|
/team-config autonomous.profile=assisted autonomous.preferAsyncForLongTasks=true --project
|
|
/team-config --unset=autonomous.preferAsyncForLongTasks --project
|
|
/team-autonomy status
|
|
/team-autonomy on
|
|
/team-autonomy off
|
|
/team-autonomy manual
|
|
/team-autonomy suggested
|
|
/team-autonomy assisted
|
|
/team-autonomy aggressive
|
|
/team-validate
|
|
/team-help
|
|
/team-doctor
|
|
```
|
|
|
|
## Management
|
|
|
|
Create resources:
|
|
|
|
```json
|
|
{
|
|
"action": "create",
|
|
"resource": "team",
|
|
"config": {
|
|
"name": "Backend Team",
|
|
"description": "Backend work",
|
|
"scope": "project",
|
|
"defaultWorkflow": "default",
|
|
"roles": [{ "name": "executor", "agent": "executor" }]
|
|
}
|
|
}
|
|
```
|
|
|
|
Rename an agent and update team references:
|
|
|
|
```json
|
|
{
|
|
"action": "update",
|
|
"resource": "agent",
|
|
"agent": "worker",
|
|
"scope": "project",
|
|
"updateReferences": true,
|
|
"config": { "name": "better-worker" }
|
|
}
|
|
```
|
|
|
|
Delete requires confirmation:
|
|
|
|
```json
|
|
{
|
|
"action": "delete",
|
|
"resource": "team",
|
|
"team": "backend-team",
|
|
"scope": "project",
|
|
"confirm": true
|
|
}
|
|
```
|