pi-cohort

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

pi-cohort

pi-cohort

Buy Me A Coffee

Coordination for the pi coding agent: one parent agent delegates to focused child agents.

The problem

A single agent reviewing its own work is theater - it shares the blind spots that produced the bug in the first place. And one agent can't hold a large task, a plan, and three parallel audits in one context without drift: the further into a task it gets, the more the earlier decisions blur.

pi-cohort gives the parent agent a subagent() tool to delegate to focused child agents, each with its own fresh context and one job. The parent stays in control and brings results back - a team with one orchestrator, not a swarm.

Why this is different

  • Fresh eyes, not the same model talking to itself. A reviewer child has no stake in the code it's checking and no memory of writing it.
  • The parent stays in control. Children don't spawn their own children unless explicitly allowed (tools: subagent), and nesting is depth-capped - no runaway fanout.
  • Delegation is a tool call, not a mode switch. You keep talking to Pi normally; it decides when a task benefits from a second set of eyes, a parallel scout, or a background run.

Part of the pi agent toolkit

Four independent extensions for the pi coding agent, each owning one concern of running agents seriously:

  • pi-quiver - capabilities (fetch, doc conversion, session tools)
  • pi-cohort - coordination (delegate to focused child agents)
  • pi-condense - context economy (prune context, keep it recoverable)
  • pi-gauntlet - process (the gated brainstorm->ship workflow)

pi-gauntlet has a hard runtime dependency on this package - its personas dispatch through subagent(). The rest are complementary, not required.

Installation

pi install npm:pi-cohort

That is the only required step.

Mental model

Pi is the parent session. A subagent is a focused child Pi session with its own job. When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. Foreground runs stream in the conversation; background runs keep working and can be checked later.

Installing the extension does not start an automatic reviewer in the background - it gives Pi a delegation tool. If you want every implementation reviewed, say so in your prompt or project instructions:

When you finish implementing, run a reviewer subagent before summarizing.

flowchart TB
    P[parent session<br/>stays in control] -->|"subagent()"| D{dispatch}
    D -->|single| C1[child: fresh context, one job]
    D -->|parallel| C2[child A]
    D -->|parallel| C3[child B]
    D -->|chain| C4[child 1] --> C5[child 2]
    C1 --> R[results]
    C2 --> R
    C3 --> R
    C5 --> R
    R --> P

Quick example

You do not need to create agents, write config, or learn slash commands. After installing, ask Pi for delegation in plain language:

Use reviewer to review this diff.

Ask oracle for a second opinion on my current plan.

Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.

That's the whole surface for day-to-day use. More phrasing patterns: doc/commands.md.

Architecture

subagent() supports four dispatch shapes, all through the same tool:

Mode Use it for
Single One focused child: review a diff, scout a codebase, plan a change.
Parallel N children at once, e.g. three reviewers with different angles.
Chain Sequential steps where each agent's output feeds the next (scout -> planner -> worker -> reviewer).
Async Any of the above, backgrounded, so the parent keeps working or ends its turn cleanly.

context: "fork" starts a child from a real branched session instead of a fresh one, when it needs the parent's history. Cost across the whole subtree - main loop plus every foreground/background/nested child - rolls up into one Σ$ total in the footer; see doc/observability.md.

Full reference: agent/chain authoring in doc/agents-and-chains.md, exact command syntax in doc/commands.md, the raw tool API in doc/programmatic-api.md.

Key concepts

Term Meaning
Subagent A focused child Pi session with one job and (by default) a fresh context.
Agent (persona) A markdown file with frontmatter defining a specialist: scout, planner, worker, reviewer, context-builder, oracle, delegate. Full table: doc/agents-and-chains.md.
Chain A saved or inline sequence of agent steps, with fan-out/fan-in support.
Fresh vs. forked context Fresh = clean slate; forked = a real branch of the parent's session history.
Recursion guard Depth cap on nested delegation so a child can only fan out if explicitly allowed.
Σ$ / cost:external The session-wide cost rollup, and the protocol other extensions use to report into it.

When to use / when NOT to use

Use it for: code review with a second set of eyes, parallel audits (correctness/tests/complexity as separate passes), scoping/planning before a bigger change, background work that shouldn't block the main conversation.

Don't use it for: a trivial single-shot edit - the delegation overhead isn't worth it. It's also not an always-on background reviewer; nothing runs automatically unless you or your project instructions ask for it.

Configuration

Most installs need zero configuration. Full env/JSON reference: doc/configuration.md.

Parent extension CLI flags (e.g. pi-lens's --no-autofix) are forwarded into spawned children by default, so subagents inherit the same tooling behavior you launched with; toggle with forwardParentFlags.

Optional companions:

Deeper reference

Relationship to the other repos

pi-gauntlet's gated workflow runs its planner/implementer/reviewer personas through this package's subagent() - without pi-cohort, gauntlet has no dispatch mechanism. pi-condense reports its own summarization spend through the cost:external protocol this package aggregates into Σ$ (see doc/observability.md). pi-quiver has no code coupling here.

Roadmap

See CHANGELOG.md for shipped work in progress.

Support

If pi-cohort is useful, consider buying me a coffee.

本页内容由上游仓库自动镜像，如有疑问请访问原始仓库。