Pi Shadow Mind

Configurable cognitive cores for Pi.

English · 中文

Pi Shadow Mind runs specialized agents alongside the main agent. Each Shadow Mind owns a persistent responsibility—architecture, correctness, documentation, project grounding, or anything else you define.

While the main agent implements, other minds can independently review decisions, verify claims, maintain related files, and intervene before mistakes become expensive to undo.

Build and review in the same pass.

One agent, multiple responsibilities

The main agent keeps moving. Shadow Minds independently protect the parts of the work that matter to you.

Cognitive core	Responsibility
Architecture review	Detect growing god components, misplaced responsibilities, missing module boundaries, and fragile extension points while code is being written
Project grounding	Check claims against the actual repository and catch invented APIs, files, constraints, or implementation details
Documentation maintenance	Track implementation changes and keep architecture notes, decisions, and usage documentation aligned
Completion review	Independently verify that the result satisfies the task before the main agent declares it finished

These are not temporary tasks delegated by the main agent. They are persistent, user-defined cognitive roles that decide independently when to inspect, act, or report.

Shadows can review—or work

A Shadow Mind may remain read-only and report findings to the main agent, or receive additional tools and own a parallel line of work.

While the main agent writes code, another Shadow can maintain documentation, update architectural decisions, or work on a separate file. Tool access is configured per Shadow, so each cognitive core receives only the capabilities its responsibility requires.

Main Agent          Architecture Shadow
implements feature  reviews module boundaries

Main Agent          Documentation Shadow
writes code         maintains design documentation

Review is only one possible responsibility. A Shadow Mind can observe, verify, maintain, or build.

Start with an Architecture Shadow

Create ~/.pi/agent/shadow-minds/architecture-review.md:

---
id: architecture-review
name: Architecture review
activation_probability: 0.3
trigger: [heartbeat]
active_for_models: ["*"]
tools: [read, grep]
---

Review the main agent's current implementation for architectural drift.

Check whether responsibilities have clear owners, modules have coherent
boundaries, and new behavior uses appropriate extension points. Detect growing
god components, unrelated state or methods accumulating in one module, and
business differences implemented as expanding conditionals.

Report only concrete, actionable issues grounded in the visible trajectory or
repository. If the current work is unrelated, do not intervene.

This Shadow is read-only. It reviews the implementation in parallel and reports concrete architectural concerns without taking control of the main task. Tool names extend the default read-only set; use tools: ["*"] only when the Shadow should inherit every tool currently registered in the main session, including tools added later.

How it works

Each Shadow chooses one or both activation triggers with trigger. The default is [heartbeat]: after a main-agent turn_end that completed at least one tool call, the extension evaluates the global heartbeat probability, then eligible Shadows roll independently using activation_probability. Pure text-only conversation turns are skipped. The global configuration heartbeat_tools restricts which Main tools can trigger a heartbeat evaluation; individual Shadows can use activation_tools to restrict their own heartbeat eligibility. Both default to [] (no filtering) and match any listed tool by exact name, e.g. [edit, write]. Config is refreshed before filtering each tool-bearing turn. These filters apply only to heartbeat, not final_response, and are separate from tools, which grants tools to the Shadow itself.

Use trigger: [final_response] for completion review. It activates after the main agent has emitted its final text and bypasses both heartbeat and activation probability. All checks for that final response finish before their findings are sent together through one shadow-report follow-up, so a slow sibling cannot leak into a revised answer. trigger: [heartbeat, final_response] enables both modes. max_parallel_shadows remains the concurrency limit; excess final-response checks are queued rather than skipped.

Each activation starts a fresh temporary session. It inherits the main agent's unchanged system prompt but receives only a sanitized plain-text trajectory: assistant thinking is removed, while tool calls retain compact, deterministic result summaries.

A Shadow first decides whether the trajectory is relevant to its responsibility. If unrelated, it exits without calling tools or report_to_main. When the main agent should receive a concrete result, the Shadow calls report_to_main, which immediately ends that run.

Shadow definitions are ordinary Markdown files. They can be created and adjusted by the user or managed by the agent through the extension's tools. Model filters and activation probabilities allow different models to receive different supporting minds.

Installation

pi install npm:pi-shadow-mind

On the first session start, the extension creates:

~/.pi/agent/shadow-minds/
  config.json
  *.md
  logs/<shadow-id>/*.jsonl   # only when debug: true

No default Shadow Mind is created. The global runtime timeout defaults to 300 seconds, and individual Shadows may override it with timeout_seconds.

Press F6 or Alt+S to pause or resume Shadow Mind for the current session. On macOS, you may need Fn+F6; Alt+S corresponds to Option+S and depends on the terminal's Option key mapping. The paused footer reads 🐙 Paused without a redundant zero count. Use /shadow to toggle the status panel, /shadow status for a summary, or /shadow toggle, /shadow pause, and /shadow resume for command-based control. In TUI mode, /shadow reports opens a bounded, scrollable viewer for the five most recently delivered reports, independent of the recent-run list. Use ↑/↓, PageUp/PageDown, or Home/End to scroll; Escape or /shadow reports hide closes it. The viewer shows a snapshot; reopen to see new deliveries. Report history is session-local and clears on session replacement or reload; persisted reports remain in the conversation. The status panel keeps its compact summary. Management tools can list, create, update, enable, disable, and delete Shadow Minds, as well as read or update the global configuration. Every write requires user confirmation.

Using with DSH

To use Shadow Mind in DSH, see whutzefengxie-ops/dsh-shadow-mind. That project provides the DSH-specific integration.

Development

npm install
pi -e ./src/index.ts

See DESIGN.md for the behavioral contract and BENCHMARK.md for benchmark methodology and lessons learned.