Orch Pi Extension

Orch is a multi-agent orchestration extension for Pi.

It adds:

• interactive orchestrator behavior during normal chat
• a Claude Code-like TodoWrite checklist for the main Pi orchestrator
• Orch sub-agents via orch_delegate (validator runs are always fresh; other roles may reuse cached context)
• orchestrator-only advisor guidance via orch_smart_friend
• autonomous mission mode via /mission
• an Orch control surface via /orch and /orch-model
• custom footer, mission widgets, and compact tool rendering

Install

Global install

Install Orch once and use it from any directory:

pi install npm:pi-orch-extension

Or install directly from GitHub:

pi install git:github.com/AryanBhargavprojects/pi_ORCH_Extension

Pi writes global installs to ~/.pi/agent/settings.json, so Orch loads in every project on this machine.

Verify the package is installed:

pi list

If Pi is already running, reload it:

/reload

One-off try without installing globally

pi -e npm:pi-orch-extension

Local development

For local development you can keep the extension in an auto-discovered Pi extension directory such as:

.pi/extensions/orch/index.ts

That lets you iterate in-place and reload with /reload.

Current contents

• index.ts - extension entrypoint
• commands.ts - /orch command router and aliases
• footer.ts - minimal custom footer with model/context stats and reactive mascot
• model-command.ts - /orch-model sub-agent model selector and persistence
• config.ts - Orch config schema, defaults, validation, load/save helpers
• cmux-streaming.ts - caller-anchored cmux worker/validator split-pane setup and raw role stream tailing
• interactive.ts - default interactive orchestrator behavior plus TodoWrite, orch_delegate, and orch_smart_friend
• mission.ts - autonomous /mission loop, deterministic planning/steering, milestones, conditional validation, and the live mission block UI
• mission-state.ts - live mission state directory I/O, state snapshots, feature status tracking
• mission-types.ts - shared mission, milestone, fix-task, and state types
• plan.ts - Plan Mode workflow, /plan command, Ctrl+` shortcut, plan progress UI
• plan-state.ts - Plan Mode state directory I/O and artifact persistence
• plan-types.ts - shared Plan Mode types
• tool-renderers.ts - compact built-in tool rendering for subtler chat activity
• messages.ts - Orch event message renderer/helpers
• prompt-loader.ts - loads role prompts from the extension-local prompt folder
• prompts/orchestrator.md - orchestrator system prompt
• prompts/worker.md - worker system prompt
• prompts/validator.md - validator system prompt
• prompts/smart-friend.md - smart friend advisor system prompt
• role-runner.ts - Orch subagent spawner plus worker/validator wrappers and non-validator session reuse
• runtime.ts - runtime state plus footer/mission status helpers
• constants.ts - shared metadata and command names
• utils.ts - shared helpers for slug generation and error formatting
• package.json - Pi package metadata for npm/git distribution

Registered commands

Primary entrypoints:

• /orch - Orch control center
• /orch status - runtime and config summary, including live mission state from state.json when a mission is active
• /orch config - show merged config plus user/project overrides
• /orch config paths - show config file paths and resolved Orch storage paths
• /orch config init user|project [force] - write a scaffold config file
• /orch config set user|project <key> <value> - persist a specific setting
• /orch takeover [prompt] - interrupt an active mission and return to interactive control
• /orch reload - reload Pi so Orch changes are picked up immediately
• /orch-model [user|project] [role] [provider/model] - select a Pi-available model for Orch sub-agents
• /mission <goal> - start explicit autonomous mission mode
• /plan <goal> - start Plan Mode (read-only analysis, no project edits)
• /plan status - report active plan status
• /plan cancel - abort active plan
• Ctrl+` - enter Plan Mode using editor text or prompt for goal

Compatibility aliases:

• /orch-status
• /orch-reload
• /orch-takeover [prompt]

Pi's built-in /reload command also works.

Interactive mode

Normal conversation runs with Orch interactive orchestration guidance injected into the system prompt.

Footer

Orch now installs a custom minimal footer in the Pi TUI.

Footer contents only:

• current model name
• current thinking level for reasoning-capable models
  • mirrors Pi's live Shift+Tab thinking-cycle behavior
  • models with xhigh support show off|minimal|low|medium|high|xhigh
  • reasoning-capable models without xhigh show off|minimal|low|medium|high
  • non-reasoning models hide the thinking-level indicator
• current context usage as used/total
• a small animated cyber/geek mascot

Mascot behavior:

• idle when nothing is running
• thinking during normal chat turns
• tool while tools are executing
• orchestrator when the main Pi agent is coordinating Orch work
• worker during feature execution phases
• validator during validation phases
• success, error, and interrupted as short transient reactions

Additional custom tools:

• TodoWrite - maintain a short live checklist for multi-step work in the main Pi orchestrator session
• orch_delegate - run an Orch role session with:
  • worker
  • validator
  • plan_codebase
  • plan_researcher
• orch_smart_friend - ask a read-only advisor for a second opinion when the orchestrator is stuck

This gives the main conversational agent a way to orchestrate directly, keep visible progress with todos, delegate focused sub-tasks using the role-specific models from Orch config, and consult a stronger read-only advisor when needed.

Validation is conditional during normal orchestration unless a stricter mission-stage validation step is triggered.

Sub-agent model configuration

/orch-model is the Orch-side model selector for sub-agents.

It is intended to mirror Pi's normal /model flow, but for Orch roles instead of the active main session.

Behavior:

• reads the same Pi model registry used by /model
• only shows models that are currently available/authenticated in Pi
• lets the user choose which Orch role to configure:
  • orchestrator (main-agent prompt role metadata; not spawned as a sub-agent)
  • worker
  • validator
  • smart_friend
  • plan_clarifier
  • plan_codebase
  • plan_researcher
  • plan_feasibility
  • plan_synthesizer
• lets the user choose which config scope to write to:
  • project scope
  • user scope
• persists the selected provider/model pair into Orch config
• the selected worker/validator/smart-friend/plan role models are used by Orch sub-agents during delegation, /mission, and /plan runs

Interactive flow:

• /orch-model
  • prompts for scope
  • prompts for role
  • prompts for model from Pi's available model list
• /orch-model worker
  • prompts only for scope and model
• /orch-model project validator
  • prompts only for model

Examples:

/orch-model
/orch-model worker
/orch-model project validator
/orch-model worker anthropic/claude-sonnet-4-5
/orch-model user orchestrator openai/gpt-5

Sub-agent architecture

Orch validator sub-agents always run as fresh Pi SDK sessions with isolated context. Other Orch roles may reuse cached Pi SDK session context when the cwd/role/model/tool setup matches.

Implemented pieces:

• Subagent spawner - spawnOrchSubagent() in role-runner.ts
• Worker sub-agent wrapper - runOrchWorkerSubagent()
  • receives a feature spec plus mission shared-state context
  • implements the feature and any generated fix tasks
  • returns a structured handoff for the main Pi orchestrator and validator consumption
• Validator sub-agent wrapper - runOrchValidatorSubagent()
  • receives the worker handoff plus mission shared-state context
  • reviews the repository state
  • flags issues with severity and action items
• Shared mission state access
  • every role receives the mission state directory + file paths in its task prompt
  • roles can read the shared state files directly during execution
  • workers receive guidelines + knowledge base + feature status summary
  • validators receive knowledge base + feature status summary
  • failed validation is converted into deterministic fix tasks without spawning an orchestrator sub-agent

Autonomous mission mode

/mission <goal> runs an isolated Orch loop:

1. The main Pi agent orchestrates the mission
2. Orch creates a simple mission plan from the goal
3. Orch creates a live mission state directory under paths.missionsDir/<mission-id>/
4. Worker sub-agent executes each feature, usually reusing its cached role session context when the configuration matches
5. Validator sub-agent reviews a feature only when conditional policy says validation is needed; validator runs are always fresh
6. If validation fails, Orch generates deterministic fix tasks and optional follow-up instructions
7. Worker executes the fix tasks on the next attempt
8. After each milestone, validator performs milestone-level validation
9. Validator performs final mission validation
10. Final mission record is written to paths.missionsDir

Phase 4 behavior now implemented:

• Live mission block UI
  • the main Pi pane shows a single mission-control block above the editor during active missions
  • the block is styled as a distinct dark status panel instead of footer-like text
  • it combines the mission goal, current task, live checklist from features.json, and the latest orchestrator update
  • orchestrator visibility stays in the main Pi pane instead of a separate cmux pane
  • planned features and generated fix tasks both appear in the checklist
  • routine mission progress chatter is suppressed from the main transcript so the mission block becomes the primary UI
  • the block clears automatically when the mission completes or is interrupted
• Interrupt and take-over
  • use /orch takeover or /orch-takeover
  • or simply type a normal prompt while a mission is running
  • Orch aborts the active mission and hands control back safely
  • if you typed a prompt during mission execution, Orch delivers it after the mission has stopped
• cmux split-pane streaming
  • when Orch is running inside cmux, a mission creates persistent role panes for:
    • worker
    • validator
  • the orchestrator stays in the main Pi mission block on the left
  • pane creation is anchored to the current caller pane/workspace only, so Orch splits the active workspace instead of creating or drifting into a separate workspace view
  • if cmux cannot resolve the caller pane/workspace reliably, Orch skips split-pane streaming instead of guessing
  • panes are created once per mission, not once per feature
  • worker runs stream sequentially into the same worker pane across the mission
  • validator runs stream sequentially into the same validator pane across the mission
  • raw thinking/text deltas are appended to role-specific mission logs and tailed live in the cmux panes
  • pane management is cmux-only for v1 and uses cmux's programmable API
• Externalized mission state
  • every mission now creates a live state directory:
    • plan.json
    • features.json
    • validation-contract.md
    • knowledge-base.md
    • guidelines.md
    • state.json
  • features.json tracks feature status with pending, in-progress, done, and failed
  • generated fix tasks are externalized into the feature state as mission-visible fix entries
  • knowledge-base.md accumulates validator findings and deterministic fix-plan notes
  • guidelines.md stores planning-time guidance plus steering-time updates
  • state.json is updated at phase transitions and powers live /orch status mission progress
• Milestones and milestone validation
  • mission plans now include milestone groups
  • Orch validates each milestone as an integrated unit before proceeding
  • milestone results are persisted in the final mission record
• Fix-task loop
  • validator failures now flow through an explicit loop:
    • validator flags issues
    • Orch creates deterministic fix tasks without an orchestrator sub-agent
    • worker executes those fix tasks on the next attempt
• Minimal reactive footer
  • the built-in footer is replaced by a single-line custom Orch footer
  • it shows only model name, current thinking level, current context usage, and an animated mascot
  • thinking-level display mirrors Pi's model-capability behavior exactly
  • the mascot reacts to normal chat work and Orch mission phases
• Compact tool activity rendering
  • built-in read, bash, edit, write, find, grep, and ls tool output is rendered in a subtler two-line activity style
  • collapsed tool rows show concise summaries instead of dumping raw output by default
  • ctrl+o still expands the row to show the underlying detailed output or diff

Plan Mode

/plan <goal> runs a read-only planning workflow that produces a structured plan without modifying the project. Plan sub-agents use read-only tools plus a bash allowlist for safe inspection commands. A live Plan Control block appears above the editor with phase, active sub-agent, elapsed time, latest activity, checklist, and artifact path.

Workflow phases:

1. Clarifier - refines the goal and asks clarification questions if needed
2. Codebase analysis - inspects the repository with read-only tools
3. Docs/web research - reviews repo docs and performs best-effort external docs/web lookup when available
4. Feasibility assessment - evaluates technical risks and approach
5. Synthesis - produces final plan.md and validation-contract.md

Plan artifacts are written to .pi/orch/plans/<plan-id>/:

• brief.md - original and refined goal with assumptions
• questions.json - clarification questions and answers
• research/codebase-analysis.md - codebase analysis report
• research/docs-web-research.md - documentation research report
• feasibility.md - feasibility assessment
• plan.md - final implementation plan
• validation-contract.md - acceptance criteria for validation
• state.json - runtime plan state

Shortcuts:

• Ctrl+` enters Plan Mode using editor text (or prompts for a goal if editor is empty)
• /plan status shows active plan phase and state directory
• /plan cancel aborts an active plan

If an agent turn or mission is already running, the shortcut notifies instead of starting a second plan.

After completion, Orch suggests running /mission <refined goal> to execute the plan autonomously.

Plan Mode role models are configurable through /orch-model using plan_clarifier, plan_codebase, plan_researcher, plan_feasibility, and plan_synthesizer. If a plan role is not explicitly configured, it inherits the current merged orchestrator model so existing project configs keep working.

Config files

Orch merges config from two scopes:

• user-level: ~/.pi/agent/orch/config.json
• project-level: <project>/.pi/orch/config.json

Merge order:

1. Orch defaults
2. user config
3. project config

Project config overrides user config.

Config schema

{
  "roles": {
    "orchestrator": { "provider": "anthropic", "model": "claude-opus-4-5" },
    "worker": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
    "validator": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
    "smart_friend": { "provider": "anthropic", "model": "claude-opus-4-7" },
    "plan_clarifier": { "provider": "anthropic", "model": "claude-opus-4-5" },
    "plan_codebase": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
    "plan_researcher": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
    "plan_feasibility": { "provider": "anthropic", "model": "claude-opus-4-5" },
    "plan_synthesizer": { "provider": "anthropic", "model": "claude-opus-4-5" }
  },
  "tokenThresholds": {
    "learningExtraction": 100000,
    "contextWarning": 80000
  },
  "paths": {
    "userProfileFile": "orch/user-profile.json",
    "projectContextFile": ".pi/orch/project-context.json",
    "knowledgeBaseFile": ".pi/orch/knowledge-base.json",
    "missionsDir": ".pi/orch/missions",
    "adaptationLogFile": ".pi/orch/adaptation-log.jsonl",
    "plansDir": ".pi/orch/plans"
  }
}

Relative path resolution:

• paths.userProfileFile resolves relative to ~/.pi/agent/
• project paths resolve relative to the project root
• absolute paths are preserved as-is

Prompt folder

Role prompts live in the package-local prompts/ directory.

Files:

• prompts/orchestrator.md
• prompts/worker.md
• prompts/validator.md
• prompts/smart-friend.md
• prompts/plan_clarifier.md
• prompts/plan_codebase.md
• prompts/plan_researcher.md
• prompts/plan_feasibility.md
• prompts/plan_synthesizer.md

The interactive orchestrator prompt and Orch sub-agent session behavior load from these files.

Hot-reload dev workflow

1. Start Pi from the project that has Orch installed locally.
2. Edit the Orch package files.
3. Inside Pi, run either:
   • /orch reload
   • /orch-reload
   • /reload
4. Run /orch status to confirm the new runtime loadedAt timestamp and active config

Notes

• No build step is required for now; Pi loads the TypeScript directly via its extension loader.
• Validator sessions are created with the Pi SDK in fresh in-memory sessions; other Orch roles may reuse cached in-memory sub-agent sessions until Orch shuts down.
• Mission runs write a JSON mission record under the configured missionsDir.
• While a mission is running, Orch also maintains a human-readable/live mission state directory under paths.missionsDir/<mission-id>/.