pi-cohort

KO | EN

gitlite — search

#nextjs #awesome-list #svg #api #chatbot #animation #vue #generative-ai #gpt #electron

(★ 9)

pi extension for async subagent delegation with truncation, artifacts, and session sharing

파일 탐색기

ZIP 다운로드

- - bug_report.md
  - config.yml
  - feature_request.md
- - release.yml
  - test.yml
- FUNDING.yml
- pull_request_template.md
- gauntlet-overrides.md
- context-builder.md
- delegate.md
- monitor.md
- oracle.md
- planner.md
- reviewer.md
- scout.md
- worker.md
- - 2026-06-15-drop-pi-web-access-remove-researcher.md
  - 2026-06-16-in-flight-turn-activity-state.md
  - 2026-09-06-pi-cohort-mux-context-transfer.md
- - 2026-06-12-tools-prepend-append-drop-mcp.md
  - 2026-06-15-drop-pi-web-access-remove-researcher.md
  - 2026-06-16-in-flight-turn-activity-state.md
  - 2026-06-19-grand-total-cost-status.md
  - 2026-06-21-cost-external-protocol.md
  - 2026-06-27-persona-discovery-walk-to-git-root.md
  - 2026-06-28-foreground-silence-killcap.md
  - 2026-07-16-top-level-artifacts-opt-in.md
  - 2026-07-19-forward-parent-cli-flags.md
  - 2026-08-06-subagent-schema-diet.md
  - 2026-08-07-subagent-schema-diet-round-three.md
  - 2026-08-08-subagent-schema-diet-round-two.md
  - 2026-08-18-gh-7-steer-foreground-control-notices.md
  - 2026-09-01-async-runner-diagnosability-monitor-sidecar.md
  - 2026-09-01-gh-8-run-scoped-worktree-artifacts.md
  - 2026-09-01-gh-9-async-typebox-empty-evidence.md
  - 2026-09-06-gh-10-windows-eperm-temp-dir-retry.md
  - 2026-09-06-gh-11-remove-pi-intercom.md
  - 2026-09-06-mux-execution-backends.md
  - 2026-09-07-gh-13-nested-grand-total.md
- agents-and-chains.md
- commands.md
- configuration.md
- observability.md
- orchestration-patterns.md
- programmatic-api.md
- skills-and-companions.md
- gather-context-and-clarify.md
- parallel-cleanup.md
- parallel-context-build.md
- parallel-handoff-plan.md
- parallel-review.md
- review-loop.md
- check-agents-core.mjs
- - SKILL.md
- - agent-management.ts
  - agent-scope.ts
  - agent-selection.ts
  - agent-serializer.ts
  - agents.ts
  - chain-serializer.ts
  - frontmatter.ts
  - identity.ts
  - skills.ts
- - child-host-controller.ts
  - child-host-protocol.ts
  - child-host-runtime.ts
  - configured-selection.ts
  - control-channel.ts
  - control-protocol.ts
  - index.ts
  - registry.ts
  - reload.ts
  - reporting-extension.ts
  - reporting-protocol.ts
  - selection.ts
  - session-replay.ts
  - session-watcher.ts
  - testkit.ts
  - types.ts
- - config.ts
  - control-notices.ts
  - doctor.ts
  - fanout-child.ts
  - grand-total.ts
  - index.ts
  - mkdir-with-retry.ts
  - schemas.ts
- - artifacts.ts
  - atomic-json.ts
  - file-coalescer.ts
  - fork-context.ts
  - formatters.ts
  - jsonl-writer.ts
  - model-info.ts
  - post-exit-stdio-guard.ts
  - session-identity.ts
  - session-tokens.ts
  - settings.ts
  - status-format.ts
  - types.ts
  - utils.ts
- - prompt-template-bridge.ts
  - slash-bridge.ts
  - slash-commands.ts
  - slash-live-state.ts
- - render-helpers.ts
  - render.ts
- - async-execution.test.ts
  - async-job-tracker.test.ts
  - async-status.test.ts
  - background-external-execution.test.ts
  - chain-clarify.test.ts
  - chain-execution.test.ts
  - detached-external-orchestration.test.ts
  - detect-error.test.ts
  - doctor-executor.test.ts
  - error-handling.test.ts
  - execution-backend-package.test.ts
  - execution-backend-reload.test.ts
  - execution-backend-testkit-consumer.test.ts
  - execution-child-host.test.ts
  - execution-control-reporting.test.ts
  - execution-reporting-extension.test.ts
  - fanout-child-own-subagent-history.test.ts
  - flag-forwarding.test.ts
  - foreground-external-execution.test.ts
  - foreground-in-flight-control.test.ts
  - foreground-result-size.test.ts
  - fork-context-execution.test.ts
  - nested-child-grand-total.test.ts
  - parallel-execution.test.ts
  - render-fork-badge.test.ts
  - render-widget.test.ts
  - result-watcher.test.ts
  - session-tokens.test.ts
  - single-execution.test.ts
  - slash-commands.test.ts
  - slash-live-state.test.ts
  - template-resolution.test.ts
  - top-level-async.test.ts
- - helpers.ts
  - mock-pi-script.mjs
  - mock-pi.ts
  - register-loader.mjs
  - ts-loader.mjs
- - acceptance.test.ts
  - agent-disabled.test.ts
  - agent-frontmatter.test.ts
  - agent-management.test.ts
  - agent-overrides.test.ts
  - agent-scope.test.ts
  - agent-selection.test.ts
  - agents.discovery-walk.test.ts
  - artifacts.test.ts
  - async-execution.test.ts
  - async-resume.test.ts
  - background-external-attempt.test.ts
  - chain-serializer.test.ts
  - close-grace-timer.test.ts
  - completion-dedupe.test.ts
  - completion-guard.test.ts
  - control-notices.test.ts
  - doctor.test.ts
  - dynamic-fanout.test.ts
  - execution-backend-configured-selection.test.ts
  - execution-backend-conformance-spi.test.ts
  - execution-backend-project-settings.test.ts
  - execution-backend-registry.test.ts
  - execution-backend-reload.test.ts
  - execution-backend-selection.test.ts
  - execution-backend-testkit.test.ts
  - execution-child-host-controller.test.ts
  - execution-child-host-protocol.test.ts
  - execution-control-channel.test.ts
  - execution-control-protocol.test.ts
  - execution-reporting-protocol.test.ts
  - execution-session-replay.test.ts
  - execution-session-watcher.test.ts
  - external-foreground-execution.test.ts
  - external-single-attempt.test.ts
  - file-coalescer.test.ts
  - foreground-execution-routing.test.ts
  - foreground-tool-call-compaction.test.ts
  - fork-context.test.ts
  - forward-flags.test.ts
  - get-final-output.test.ts
  - grand-total-cost.test.ts
  - index-child-registration.test.ts
  - jsonl-writer.test.ts
  - mkdir-with-retry.test.ts
  - model-fallback.test.ts
  - model-info.test.ts
  - monitor-persona.test.ts
  - nested-control.test.ts
  - nested-events.test.ts
  - notify.test.ts
  - package-manifest.test.ts
  - parallel-utils.test.ts
  - path-handling.test.ts
  - path-resolution.test.ts
  - pi-args.test.ts
  - pi-coding-agent-dir.test.ts
  - pi-spawn.test.ts
  - prompt-template-bridge.test.ts
  - recursion-guard.test.ts
  - render-helpers.test.ts
  - result-children.test.ts
  - run-id-resolver.test.ts
  - run-status.test.ts
  - schemas.test.ts
  - single-output.test.ts
  - skills-fallback.test.ts
  - stale-run-reconciler.test.ts
  - status-format.test.ts
  - subagent-control.test.ts
  - subagent-prompt-runtime.test.ts
  - temp-paths.test.ts
  - tool-description.test.ts
  - ts-loader.test.ts
  - types-fork-preamble.test.ts
  - widget-nested-render.test.ts
  - windows-hide-spawn.test.ts
  - workflow-graph.test.ts
  - worktree.test.ts
.gitignore
AGENTS.core.md
AGENTS.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
package.json
pi-cohort.png
README.md

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

# 프로젝트 배지

Buy Me A Coffee 바로가기

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Coordination for the [pi coding agent](https://github.com/earendil-works/pi): 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](https://github.com/earendil-works/pi), each owning one concern of running agents seriously:

- [pi-quiver](https://github.com/jjuraszek/pi-quiver) - capabilities (fetch, doc conversion, session tools)
- **pi-cohort - coordination (delegate to focused child agents)**
- [pi-condense](https://github.com/jjuraszek/pi-condense) - context economy (prune context, keep it recoverable)
- [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) - process (the gated brainstorm->ship workflow)

[pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) has a hard runtime dependency on this package - its personas dispatch through `subagent()`. The rest are complementary, not required.

## Installation

```bash
pi install npm:pi-cohort
```

That is the only required step.

## Execution backend extension API

External execution backends are currently unsupported on Windows, for both foreground and background runs. Native execution remains supported.

`pi-cohort/execution-backend` requires Pi >=0.85.0 and is the public API for Pi extensions that add child execution surfaces. Pi's TypeScript-aware runtime loads the API; bare Node is not a supported execution path. Consumers outside Pi must supply a TypeScript-aware loader such as [jiti](https://github.com/unjs/jiti).

An adapter registers its backend in extension load order. To make that backend available to background runs, registration also supplies an optional reload descriptor:

```ts
import {
  EXECUTION_BACKEND_PROTOCOL_VERSION,
  registerExecutionBackend,
  type ExecutionBackendFactory,
} from "pi-cohort/execution-backend";
import { createBackend } from "./adapter.ts";

export const createExampleBackend: ExecutionBackendFactory = createBackend;

// src/execution-backend.ts, exported as "./execution-backend".
// Pi invokes the default extension; the coordinator invokes only the factory.
export default async function () {
  registerExecutionBackend(await createExampleBackend(), {
    reload: {
      protocolVersion: EXECUTION_BACKEND_PROTOCOL_VERSION,
      packageJsonUrl: new URL("../package.json", import.meta.url).href,
      publicSubpath: "./execution-backend",
      factoryExport: "createExampleBackend",
    },
  });
}
```

The descriptor has exactly four fields. `packageJsonUrl` must be an absolute `file:` URL for the adapter package's real `package.json`. `publicSubpath` must be `"."` or an explicit non-pattern `"./..."` entry in that package's `exports`. `factoryExport` names a public, zero-argument export from that subpath; it may return the backend or a promise of it. The reconstructed backend must have the same `name` and protocol version as the original registration.

Cohort serializes only backend names and validated reload descriptors into its detached coordinator - never live backend objects or an environment capsule. The coordinator reloads registrations in their original order before selecting a backend, and every child launch receives its exact resolved `cwd`. Selecting `native` bypasses reload entirely. An explicit backend selection reports that backend's reload failure; `auto` reports any registered reload failure rather than silently changing policy. Once reload succeeds, normal auto-detection still falls back to native when no registered backend is available. Backends registered without `reload` remain usable in the foreground but cannot be reconstructed for a background run.

## 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:

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

```mermaid
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:

```text
Use reviewer to review this diff.
```

```text
Ask oracle for a second opinion on my current plan.
```

```text
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](doc/commands.md#prompt-cookbook-appendix).

## 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](doc/observability.md).

Full reference: agent/chain authoring in [doc/agents-and-chains.md](doc/agents-and-chains.md), exact command syntax in [doc/commands.md](doc/commands.md), the raw tool API in [doc/programmatic-api.md](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`, `monitor`. Full table: [doc/agents-and-chains.md](doc/agents-and-chains.md#builtin-agents-in-plain-english). |
| 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](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`](doc/configuration.md#forwardparentflags).

Optional companions:

- [pi-essentials](https://github.com/jjuraszek/pi-essentials) - lets `context-builder` read referenced URLs. [doc/skills-and-companions.md](doc/skills-and-companions.md#optional-pi-essentials-companion)

## Deeper reference

- [doc/agents-and-chains.md](doc/agents-and-chains.md) - builtin agents, frontmatter, overrides, chain files and variables
- [doc/commands.md](doc/commands.md) - exact slash-command syntax, prompt cookbook
- [doc/programmatic-api.md](doc/programmatic-api.md) - the raw `subagent()` tool parameters
- [doc/configuration.md](doc/configuration.md) - all settings keys
- [doc/observability.md](doc/observability.md) - where runs show up, cost tracking, events
- [doc/skills-and-companions.md](doc/skills-and-companions.md) - skills injection, bundled skill, optional companions
- [doc/orchestration-patterns.md](doc/orchestration-patterns.md) - recommended loop, acceptance gates, worktree isolation, recursion guard

## 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](doc/observability.md)). `pi-quiver` has no code coupling here.

## Roadmap

See [CHANGELOG.md](CHANGELOG.md) for shipped work in progress.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) - issues follow a Context / Problem / Idea / Acceptance Criteria template; PRs run the [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) workflow (one-liners exempt from ceremony, never from keeping docs truthful).

## Support

If `pi-cohort` is useful, consider [buying me a coffee](https://buymeacoffee.com/jjurasszek).

pi-cohort

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

# 프로젝트 배지

Was this content helpful?

Recent Feedback

pi-cohort

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

# 프로젝트 배지

Was this content helpful?

Recent Feedback

Download README