liu-zhengdong/pi-shadow-mind

What it solves

Pi Shadow Mind addresses the issue of main AI agents drifting from architectural standards, making factual errors about a codebase, or failing to maintain documentation while implementing features. It prevents expensive mistakes by introducing specialized, persistent "cognitive cores" that review and verify work in parallel with the main agent's execution.

How it works

The system runs specialized agents (Shadow Minds) alongside a primary agent. These Shadows are defined in Markdown files and assigned specific responsibilities, such as architecture review or project grounding.

They activate based on triggers: a "heartbeat" (probabilistic activation after a main agent tool call) or a "final response" (activation after the main agent finishes its task). When active, a Shadow starts a temporary session with a sanitized version of the main agent's trajectory. It then decides if the current work is relevant to its role; if so, it can use assigned tools to inspect the project and use a report_to_main function to send findings back to the main agent.

Who it’s for

Developers using the Pi agent framework who want to ensure high-quality code architecture, accurate documentation, and strict adherence to project constraints without manually reviewing every step.

Highlights

• Persistent Roles: Unlike temporary tasks, Shadow Minds are user-defined roles that independently decide when to intervene.
• Configurable Activation: Supports both probabilistic heartbeat triggers and guaranteed final-response checks.
• Granular Tool Access: Each Shadow can be restricted to read-only access or given specific tools to perform parallel work.
• Model Filtering: Allows different models to be assigned different supporting minds based on configuration.