Skip to main content
Glama
TouHousand-Years

pi-subagent

by TouHousand-Years
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Pi-Team

Delegate tasks to the Pi CLI through MCP, with named sessions, sync/async execution and a read-only transcript window on Windows.

Based on guyiicn/pi-subagent.

Install

Requires Node.js, npm and Pi configured with access to a model provider.

npm install -g @earendil-works/pi-coding-agent
git clone https://github.com/TouHousand-Years/Pi-Team.git
cd Pi-Team
npm ci
npm run build

Ensure pi is on the MCP server's PATH. Run npm run build again after updating the checkout.

Related MCP server: pi-delegate-mcp

Configure

Add this to your MCP host configuration, using the absolute path to dist/server.js:

{
  "mcpServers": {
    "pi-subagent": {
      "command": "node",
      "args": ["/absolute/path/to/Pi-Team/dist/server.js"]
    }
  }
}

On Windows, use a path such as C:/Projects/Pi-Team/dist/server.js. The MCP server keeps the name pi-subagent for compatibility.

Adapted skills

This repository includes five skills under skills/ that turn the two MCP tools into reusable, checkable workflows. The skills do not add new server tools: they define how the host scopes work, delegates it to Pi, verifies the result and stops safely.

Skill

Use it for

Main boundary

pi-team

The shared delegation contract used by the other Pi skills: model selection, prompt composition, file ownership, result collection, concurrency and failure handling.

It supplies transport rules only; the active specialized skill still defines the task, outputs and acceptance criteria.

pi-explorer

Evidence-backed repository investigation, including architecture, tests, recent commits, caches, frontends, concurrency, networking and reproducible failures.

It keeps product files read-only and returns conclusions with paths, line references, commands and explicit evidence gaps.

pi-worker

Bounded implementation or repository work with a closed baseline-execute-verify-correct loop. It fits coding, bulk edits, experiments, log analysis and tasks with observable checks.

Pi owns the declared output files; the host reviews them read-only and sends corrections back through another bounded delegation.

pi-translator

Long or consequential translations that require complete coverage, stable terminology and preservation of headings, tables, citations, code and formulas.

It translates from explicit source files, uses a glossary when needed and marks unresolved wording instead of silently guessing or omitting content.

pi-ultra-planner

High-leverage implementation plans, trade-off decisions and recovery plans after exploration or experiments have produced a compact evidence brief.

The planner receives text only: it has no tools, network access or write permission, and it never performs the implementation.

The usual composition is pi-explorer for facts, pi-ultra-planner for a difficult decision, and pi-worker for execution. pi-translator is a separate document workflow. All four specialized skills delegate through pi-team, which uses only pi_delegate and pi_status.

Delegate a task

Call pi_delegate:

{
  "prompt": "Review the parser and write findings to review.md.",
  "session": "review-parser",
  "cwd": "C:/Projects/example",
  "goal": "Review parser correctness",
  "mode": "sync",
  "runTimeoutMs": 240000
}

  • prompt and session are required. New sessions also require goal and an existing cwd directory.

  • Reuse session to continue a conversation after its current Run finishes. You may omit cwd and goal; an explicit cwd must match the original.

  • mode: "sync" waits for completion. mode: "async" (default) returns a runId to collect later.

  • runTimeoutMs defaults to 600000 (10 minutes). Keep synchronous calls within your host's tool-call timeout.

  • Up to four Runs can execute at once, with one per session. Runs stop after 5 minutes without recorded tool-result progress.

Optional constraints configure each call independently:

{
  "model": "<model identifier configured in Pi>",
  "thinking": "high",
  "tools": ["read", "bash", "edit", "write"]
}

Place this object under constraints in pi_delegate. excludeTools is also supported. Thinking levels are off, minimal, low, medium, high and xhigh. For tool names beyond those shown, set allowUnknownTools: true. Resend constraints when continuing a session if needed.

Collect results

Call pi_status with the returned runId:

{
  "runId": "<runId>",
  "waitTimeoutMs": 25000
}

The call waits until completion or the wait timeout (default: 25 seconds). waitTimeoutMs: 0 returns immediately. If status is still running, wait again using the same runId. Terminal states are completed, error, killed and timeout; inspect result or error as appropriate.

A host timeout does not necessarily stop the Run. If you have its runId, collect that Run before starting another. Old Run IDs are unavailable after a server restart, though session metadata and transcripts remain on disk.

Windows viewer

Each Run automatically opens a read-only transcript window on Windows. Closing it does not stop the Run. To reopen it, call pi_status with "openWindow": true.

Set PI_SUBAGENT_VIEWER=off to disable windows. Delegation and transcript capture work without the viewer.

Environment variables

Variable

Purpose / default

PI_BIN

Pi executable override.

PI_SUBAGENT_VIEWER

off disables Run Windows.

PI_SUBAGENT_POWERSHELL

Viewer executable; powershell.exe.

PI_SUBAGENT_VIEWER_SCRIPT

Override viewer/run-window.ps1.

PI_SUBAGENT_REGISTRY

Session metadata; ~/.pi-subagent/registry.json.

PI_SUBAGENT_TRANSCRIPTS

Full transcripts; ~/.pi-subagent/runs.

Transcripts include prompts and tool output. Inactive completed bundles are cleaned after 7 days, with oldest-first cleanup targeting a 2 GiB quota.

Available Tools

2 tools
pi_delegateC

委派任务给 Pi 子代理（默认 async）

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
goalNo
modeNo
promptYes
sessionYes
constraintsNo
runTimeoutMsNo
allowUnknownToolsNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits but only mentions 'default async'. It does not explain side effects, how results are returned, or whether the tool is idempotent. Critical details are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, but it is overly terse for a tool with 8 parameters. While front-loaded, it lacks structure and does not fully utilize the space to convey necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (8 parameters, nested objects, no output schema, no annotations), the description is severely incomplete. It fails to cover usage patterns, return values, or async/sync behavior beyond the default.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain any of the 8 parameters, not even the required 'prompt' and 'session'. The enum for 'mode' is mentioned only implicitly as 'default async' but no details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool delegates tasks to a Pi sub-agent with a default async mode. However, it does not differentiate from sibling tools like pi_plan or pi_session_fork, which could have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor are there any preconditions or exclusions mentioned. The description is too brief to inform decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pi_statusC

取 run 结果（long-poll）；openWindow 可重开该 Run 的只读窗口

ParametersJSON Schema
NameRequiredDescriptionDefault
runIdYes
openWindowNo
waitTimeoutMsNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions long-polling and the openWindow action, but does not disclose timeout behavior, error handling, side effects, or any authentication or rate-limit considerations. This is minimal for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of one line that front-loads the primary action. While efficient, it may be overly terse, omitting critical details, but the structure itself is clean and non-redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with three parameters, no output schema, and no annotations, the description is too sparse. It does not explain the return format, what happens on timeout, error conditions, or how openWindow interacts with the polling. An agent would lack essential information for correct invocation and interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It implicitly covers runId (the run) and explains openWindow, but it does not mention waitTimeoutMs at all, nor does it clarify the format or constraints of runId. The parameter documentation is incomplete and fails to compensate for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool retrieves run results via long-polling and can reopen a read-only window. The purpose is specific and distinct from the sibling pi_delegate, though it does not explicitly name the alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus pi_delegate. There is no mention of conditions, exclusions, or alternative tools, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedpi_delegate
    • First observedpi_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: pi_delegate initiates a task delegation, while pi_status retrieves the result of a run. There is no overlap or ambiguity between them.

Naming Consistency4/5

Both tools follow a consistent pi_ prefix and use a verb_noun pattern (delegate, status). The naming is predictable, though the set is too small to fully demonstrate a broader convention.

Tool Count3/5

Two tools is on the thin side for a subagent delegation server, but it may be sufficient for a minimal async task lifecycle. The count is borderline but not unreasonable.

Completeness3/5

The pair covers the basic delegate-and-poll lifecycle, but there is no explicit cancel, list, or error-handling tool. Agents can work around this by waiting for status, but the surface feels minimal.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers