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 goal mode via /orch goal
• an Orch control surface via /orch and /orch-model
• custom footer, goal 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
• Goal engine modules - autonomous /orch goal execution, deterministic planning/steering, milestones, conditional validation, live goal block UI, and goal state snapshots
• 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/goal 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 goal state from state.json when a goal is active
• /orch goal status - report whether an autonomous goal is running and show its current phase/state paths
• /orch goal cancel - cancel an active autonomous goal without entering takeover mode
• /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 goal 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
• /orch goal <goal> - start explicit autonomous goal mode

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
  • research
• orch_smart_friend - ask a read-only advisor for a second opinion when the orchestrator is stuck
• tinyfish - run the TinyFish web automation/search agent for current web search, source lookup, live website extraction, and scraping

cmux integration:

• When Pi runs inside cmux, Orch mirrors task/goal/todo progress to the cmux workspace sidebar using cmux set-status, cmux set-progress, and cmux log.
• Orch sends native cmux notifications with cmux notify when interactive turns, goals, or tracked todo lists complete.
• cmux calls are best-effort no-ops outside cmux and never block Orch work.

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, consult a stronger read-only advisor when needed, use cmux workspace status/notifications, and use TinyFish/Parallel/Context7-enabled research for web and docs lookup.

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

TinyFish web search agent

Orch registers a tinyfish custom tool for the main orchestrator and enables it for research sub-agents. Use it with either:

• query for broad web search (defaults to DuckDuckGo HTML search results)
• url + goal for a specific website extraction/automation task

TinyFish authentication is read from TINYFISH_API_KEY; if that is not set, Orch falls back to ~/.pi/agent/orch/tinyfish-api-key. Keep this file outside git and mode 0600.

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 sub-agent role to configure:
  • worker
  • validator
  • smart_friend
  • research
  • plan_codebase
• 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/research/plan_codebase role models are used by Orch sub-agents during delegation and /orch goal 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 research anthropic/claude-sonnet-4-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 goal 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 goal shared-state context
  • reviews the repository state
  • flags issues with severity and action items
• Shared goal state access
  • every role receives the goal 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 goal mode

/orch goal <goal> runs an isolated Orch loop:

1. The main Pi agent orchestrates the goal
2. Orch creates a simple goal execution plan from the goal
3. Orch creates a live goal state directory under the configured goal runs directory
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 goal validation
10. Final goal record is written to the configured goal runs directory

Phase 4 behavior now implemented:

• Live goal block UI
  • the main Pi pane shows a single goal-control block above the editor during active goals
  • the block is styled as a distinct dark status panel instead of footer-like text
  • it combines the goal objective, 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 goal progress chatter is suppressed from the main transcript so the goal block becomes the primary UI
  • the block clears automatically when the goal completes or is interrupted
• Interrupt and take-over
  • use /orch takeover or /orch-takeover
  • or simply type a normal prompt while a goal is running
  • Orch aborts the active goal and hands control back safely
  • if you typed a prompt during goal execution, Orch delivers it after the goal has stopped
• cmux split-pane streaming
  • when Orch is running inside cmux, a goal creates persistent role panes for:
    • worker
    • validator
  • the orchestrator stays in the main Pi goal 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 goal, not once per feature
  • worker runs stream sequentially into the same worker pane across the goal
  • validator runs stream sequentially into the same validator pane across the goal
  • raw thinking/text deltas are appended to role-specific goal logs and tailed live in the cmux panes
  • pane management is cmux-only for v1 and uses cmux's programmable API
• Externalized goal state
  • every goal 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 goal-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 goal progress
• Milestones and milestone validation
  • goal plans now include milestone groups
  • Orch validates each milestone as an integrated unit before proceeding
  • milestone results are persisted in the final goal 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 goal 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

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" },
    "research": { "provider": "anthropic", "model": "claude-sonnet-4-5" },
    "plan_codebase": { "provider": "anthropic", "model": "claude-sonnet-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",
    "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/research.md
• prompts/plan_codebase.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.
• Goal runs write a JSON goal record under the configured goal runs directory.
• While a goal is running, Orch also maintains a human-readable/live goal state directory under that directory.