ac-teams

Persistent agent teams for Pi: shared tasks, searchable messages, and optional Git worktrees. Members stay alive between assignments and can resume their native Pi sessions after stopping. No workflow engine or background service.

Install

Requires Linux, Node 22.19 or newer, and an authenticated pi executable on PATH. Interactive teams also require tmux on PATH. Tested with Pi 1.4.0 and 1.5.0.

pi install npm:ac-teams

Restart Pi after installation or updates.

Use Pi's /trust command to save approval for each project directory before launching members there; headless children cannot answer the initial trust prompt.

Use it

Use team_task for substantial solo work as well as team deliverables. Agents receive guidance to plan multi-step work, start tasks before working, and complete them after verification. Simple tasks need no list. dependencies requires verified outputs before start and finish; completionDependencies allows grounded work from an agreed interface or usable intermediate output while still requiring upstream completion before acceptance. Both support batch @key references. See task rules.

Your Pi session is the root; its child agents are members. Ask Pi to delegate a bounded assignment, for example:

Launch a member to review src/parser.ts without editing, and have it send findings back to me.

| Tool | Purpose | | --- | --- | | team_agent | Launch, inspect, stop, and resume members; manage limits and worktrees | | team_task | Plan solo or team work, create tasks in batches, and track ownership and dependencies | | team_message | Send notifications and read or search team history | | team_config | Read worker extension inventory and save an approved configuration |

/teams or /teams panel opens Tasks, Teammates, and Board. /teams teammate <name-or-id> opens a teammate directly; subcommands and teammate names autocomplete. Use the task graph or list, send feedback, and open a member's full live Pi session.

The task summary sits above the input. The agent selector sits below the input, above your existing footer, and shows descriptive names, models, and context usage. ac-teams publishes a compact team status without replacing the footer or editor supplied by other extensions. /teams config display toggles these displays independently. /teams config starts a conversation with Pi to configure lean worker extension presets, without editing files or navigating a wizard. A worker can only retain or remove extensions already loaded by its parent; it cannot add installed-but-unloaded or child-directory extensions. See worker configuration.

From an empty editor, press Down to select the team row, then Enter to open a member. A red Needs input label marks a member with an open question. Ctrl+Shift+Left returns to Main without stopping the member or dismissing its question. /teams stop stops every member; main sessions keep running. /teams join and /teams leave add this session to another team or take it out.

Use /teams reload in the main session hosting the coordinator to refresh the team. Running tools finish before members pause. Pi submits queued input and editor text first.

The main session reloads, automatically rejoins, and resumes paused work in the same sessions. Cancel while waiting to leave the team running.

In a teammate, the command refreshes only that teammate. Ordinary /reload keeps Pi's existing behavior.

Defaults allow up to 10 live members and two levels of delegation. Use the fewest useful agents.

Know the boundaries

• Members share your filesystem access unless launched with enforced access, an opt-in Docker sandbox that needs Docker and a locally built member image. All members can read all team messages, including direct messages.
• Limits cover only team_agent, not other delegation tools. Coordinate shared-file edits with file or section ownership, current-content checks, and no blind overwrites. Serialize overlapping edits or use separate worktrees when needed.
• Stop retains tasks, sessions, and worktrees. Worktree deletion is explicit and requires clean, integrated work.
• Exit confirmation needs Pi's session_before_exit hook, which installed Pi 1.4.0 lacks. Without it, shutdown cleans up but cannot ask first. Signals always bypass confirmation.

See the operations guide for recovery guarantees, storage, and the Pi dependency security advisory.

Guides

• Usage: tool actions, task rules, messages, and companion tools
• Operations: limits, stop/resume, worktrees, and security
• Enforced access: Docker-enforced read/write grants, outbound proxy and destination policy, and setup
• Development: source setup, verification, and publishing
• Implementation history: design decisions and prior art

License

MIT.