Pi Shadow Mind: persistent review agents that run alongside the main Pi agent

What problem Pi Shadow Mind solves, and for whom

A single coding agent has one context and one job at a time. It writes the feature, and the review of that feature happens later, usually by a different process or a different person, after the mistakes are already in the tree. Pi Shadow Mind moves that review into the same pass. The README describes the intent directly: "Build and review in the same pass." The main agent keeps implementing while other agents, called Shadow Minds, independently inspect decisions, verify claims and maintain related files.

The audience is narrow and specific. You need to be running Pi, because the package declares peer dependencies on @earendil-works/pi-agent-core, @earendil-works/pi-ai, @earendil-works/pi-coding-agent and @earendil-works/pi-tui. You also need to be comfortable defining agent behaviour in Markdown front matter rather than in code. The four responsibilities the README names as examples are architecture review, project grounding, documentation maintenance and completion review. Grounding is the most concrete of these: the Shadow checks claims against the actual repository and catches invented APIs, files or constraints. That is a real failure mode for any agent that writes a lot of code quickly.

How activation, triggers and the sanitized trajectory work

Each Shadow Mind is a Markdown file with front matter. The trigger field decides when it can run. With trigger: [heartbeat], the extension waits for a main-agent turn_end that completed at least one tool call, evaluates the global heartbeat probability, and then lets eligible Shadows roll independently using their own activation_probability. Text-only turns are skipped entirely, so a Shadow cannot fire on a pure conversation turn.

The filtering is layered and worth understanding before you tune anything. The global heartbeat_tools key restricts which main-agent tools can trigger a heartbeat evaluation at all. An individual Shadow can narrow that further with activation_tools. Both default to [] which means no filtering, and both match by exact tool name, so [edit, write] matches only those two. Configuration is refreshed before filtering each tool-bearing turn. These filters apply only to heartbeat and are separate from tools, which is the list that grants capabilities to the Shadow itself. Mixing those two up is the easiest way to get a Shadow that never fires, or one that fires with more access than you intended.

The final_response trigger behaves differently. It runs after the main agent emits its final text and bypasses both heartbeat and activation probability. All checks for that response finish before their findings are sent together through a single shadow-report follow-up, so a slow sibling cannot leak into a revised answer. final_response_rounds limits how many rounds run after completion: 1 allows at most one, while omitting it or setting 0 means unlimited. max_parallel_shadows is the concurrency limit, and excess final-response checks are queued rather than dropped.

Every activation starts a fresh temporary session. It inherits the main agent's unchanged system prompt but receives a sanitized plain-text trajectory: assistant thinking is stripped, and tool calls keep compact deterministic result summaries. The Shadow first decides whether the trajectory is relevant to its responsibility. If it is not, it exits without calling tools or report_to_main. When there is something concrete to say, it calls report_to_main, which ends that run immediately.

Installing Pi Shadow Mind and writing your first Shadow

The README gives one install command, run through the Pi package manager:

pi install npm:pi-shadow-mind

On the first session start the extension creates ~/.pi/agent/shadow-minds/ with a config.json, room for *.md files, and a logs/<shadow-id>/ directory that is only populated when debug is set to true. No default Shadow Mind is created, so the directory starts effectively empty and nothing reviews anything until you add a file.

The README's starting example is an architecture review Shadow. Create ~/.pi/agent/shadow-minds/architecture-review.md with this front matter and body:

---
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: tools: [read, grep] extends the default read-only set, and the README warns that tools: ["*"] should be used only when the Shadow should inherit every tool registered in the main session, including tools added later. With activation_probability: 0.3, roughly three in ten eligible heartbeats will let this Shadow roll into a run, so expect it to stay quiet on most turns.

Control is split between keys and slash commands. F6 or Alt+S pauses or resumes Shadow Mind for the current session. On macOS you may need Fn+F6, and Alt+S depends on how your terminal maps the Option key. /shadow toggles the status panel, /shadow status prints a summary, and /shadow toggle, /shadow pause and /shadow resume give the same control from the command line. In TUI mode, /shadow reports opens a bounded scrollable viewer for the five most recently delivered reports, navigated with arrow keys, PageUp/PageDown or Home/End, and closed with Escape or /shadow reports hide. That viewer shows a snapshot, so you reopen it to see new deliveries. Report history is session-local and clears on session replacement or reload, though persisted reports stay in the conversation.

Where the design gets awkward

Activation is probabilistic, and that is a deliberate trade-off with a real cost. A Shadow with activation_probability: 0.3 will miss most eligible turns. If your reason for adding a completion reviewer is that you want every finished task checked, heartbeat-based review cannot promise that. The final_response trigger is the honest answer to this, but the README notes it bypasses activation probability, which means a completion Shadow runs on every final response unless you cap it. The two modes pull in opposite directions: one is cheap and unreliable, the other is reliable and potentially expensive.

final_response_rounds exists because of a specific failure mode. Without a cap, a completion reviewer's findings can feed back into another round, and another, until something else stops it. Setting 1 allows at most one round to prevent feedback loops. That is a guard against your own configuration, and it is worth setting on any Shadow that both reads and reports on final output.

The tool-granting model is the other sharp edge. tools: ["*"] hands a Shadow every tool registered in the main session, including tools added after the Shadow file was written. A Shadow that was read-only in intent can become write-capable because someone else registered a tool. The README flags this; the configuration format does not prevent it.

The README also does not document rollback. There is no described mechanism for undoing a change made by a Shadow that owns a parallel line of work, and no described per-Shadow audit beyond the optional debug logs. If you let a Shadow maintain documentation or edit a separate file, you are responsible for whatever version control sits underneath it. The repository does include test/ and a verify script that runs typecheck and tests, which tells you the maintainers test the extension itself, not that your Shadow configurations are safe.

Pi Shadow Mind compared with a plain review agent

The obvious alternative is a second agent you invoke yourself, or a review step wired into a pre-commit hook or CI job. That approach is deterministic: it runs when the pipeline runs, on the diff it is given, and it fails the build when the check fails. Pi Shadow Mind is the opposite shape. It is ambient. Shadows decide independently when to inspect, act or report, and the README is explicit that these are not temporary tasks delegated by the main agent but persistent user-defined cognitive roles.

The practical difference shows up in what each can see. A CI reviewer sees a diff and a repository. A Shadow sees a sanitized trajectory of the current session, with assistant thinking removed and tool results reduced to compact summaries. That is a weaker signal than the full transcript, but it is available while the work is still being shaped, which is the point of the heartbeat trigger. A hook cannot tell you that responsibilities are drifting mid-implementation, because by the time it runs the implementation is done.

The cost model differs too. A CI check is a fixed cost per commit. Shadow Minds are probabilistic, so cost scales with how often they roll into a run, and a final_response Shadow scales with how often the main agent finishes. If you already have a review process that catches architecture drift reliably, adding a probabilistic layer on top mostly adds variance. Pi Shadow Mind earns its place where the review has to happen inside the session, not after it.

Maintenance, licence and what the release cadence tells you

The repository is not archived, and the last push was on 2026-09-16. Releases are frequent and small: v0.1.20 on 2026-09-07, v0.1.21 on 2026-09-12 and v0.1.22 on 2026-09-16. The version is still 0.1.x, which fits a project whose configuration surface is still moving. The front matter keys described in the README, including heartbeat_tools, activation_tools, final_response_rounds and max_parallel_shadows, are the kind of thing that can change between minor versions, so pinning a version and reading the changelog before upgrading is the realistic posture.

Upgrade cost is mostly in the Shadow files you wrote, not in the package. The package ships dist, README.md, README.zh-CN.md, DESIGN.md and DESIGN-Evolution.md, and the build runs typecheck and tests before packing. Your Markdown definitions live outside the package in ~/.pi/agent/shadow-minds/, so they survive upgrades, but they also will not be migrated for you. If a key is renamed, a Shadow can silently stop matching its trigger. The debug logs under logs/<shadow-id>/ exist for exactly this kind of diagnosis and are off unless you enable them.

The licence is MIT. That is permissive and short, and it places no conditions on how you run or modify the extension beyond keeping the notice. It says nothing about the prompts you write or the reports your Shadows produce, and it is not a substitute for checking how your own organisation treats agent-generated changes to a repository. For anything beyond that, read the LICENSE file rather than this summary.

Editorial conclusion

Adopt Pi Shadow Mind if you already run Pi and want a second pass over architecture, grounding or completion without switching tools, and you are willing to write and tune the Shadow Markdown files yourself. Do not adopt it if you need a scheduler that guarantees every change is reviewed, or if you are not on Pi, since the extension depends on Pi peer packages. Before trusting it, verify the activation behaviour in your own session: set activation_probability to 0.3 on one read-only Shadow, confirm from the logs that unrelated turns exit without a report, and check that final_response_rounds: 1 actually stops the completion loop you care about.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. liu-zhengdong/pi-shadow-mind on GitHub
4. README
5. Releases