pi-shadow-git

Git-based orchestration logging for pi subagents with Mission Control dashboard.

Enables branching, rewinding, and forking agent execution paths through automatic git commits and structured audit logging.

Installation

# Via npm (recommended)
pi install npm:pi-shadow-git

# Via git
pi install git:github.com/EmZod/pi-subagent-with-logging

# Or try without installing
pi -e npm:pi-shadow-git

Once installed, the extension and skill are automatically loaded. No manual setup required.

What's Included

Resource	Description
shadow-git extension	Commits workspace state after every turn, captures audit logs
mission-control extension	Real-time TUI dashboard for monitoring agents (/mc)
pi-subagent-orchestration skill	Complete guide for orchestrating subagents with git logging

Features

• Shadow Git Logging - Commits workspace state after every turn and agent completion
• Mission Control - Real-time TUI dashboard for monitoring 100s of agents
• Audit Trail - Structured JSONL logs for querying with jq
• Patch Capture - Captures diffs when agents modify external repos
• Killswitch - Runtime toggle to disable logging during incidents
• Fail-Open - Git errors are logged but don't block the agent

Quick Start

# 1. Create workspace
WORKSPACE="$HOME/workspaces/$(date +%Y%m%d)-task"
mkdir -p "$WORKSPACE/agents/scout1"/{workspace,output}
cd "$WORKSPACE"

# 2. Write agent plan
cat > agents/scout1/plan.md << 'PLAN'
# Plan: Research Task

## Objective
Research X and produce findings.

## Steps
1. Read the codebase
2. Document findings in output/findings.md

## Output
- output/findings.md
PLAN

# 3. Spawn agent with shadow-git
PI_WORKSPACE_ROOT="$WORKSPACE" \
PI_AGENT_NAME="scout1" \
pi --max-turns 20 'Read plan.md and execute it.'

# 4. Open Mission Control to monitor
# Type: /mc

Mission Control Dashboard

Monitor multiple agents in real-time:

/mc

Features:

• Real-time status for all agents (running, done, error, pending)
• Turn count, tool calls, error count per agent
• Auto-refresh every 2 seconds
• Scrollable list for 100s of agents

Keyboard Controls:

Key	Action
↑/↓ or j/k	Navigate agents
Enter	Toggle detail panel
s	Cycle sort mode
r	Manual refresh
q or Esc	Close dashboard

Commands

Command	Description
/mission-control	Open full Mission Control dashboard
/mc	Alias for mission-control
/shadow-git	Show logging status
/shadow-git enable	Enable logging
/shadow-git disable	Disable logging (killswitch)
/shadow-git history	Show last 20 commits

Environment Variables

Variable	Required	Description
PI_WORKSPACE_ROOT	Yes	Root of the shadow git workspace
PI_AGENT_NAME	For logging	Agent name for commits and paths
PI_SHADOW_GIT_DISABLED	No	Set to 1 to disable (killswitch)

Spawning Patterns

Blocking (Sequential)

PI_WORKSPACE_ROOT="$WORKSPACE" PI_AGENT_NAME="scout" \
pi --max-turns 20 --print 'Read plan.md and execute.'

Non-blocking (Parallel with tmux)

tmux new-session -d -s scout1 \
  "PI_WORKSPACE_ROOT='$WORKSPACE' PI_AGENT_NAME='scout1' \
   pi --max-turns 30 'Read plan.md and execute.'"

Non-blocking (Headless)

(PI_WORKSPACE_ROOT="$WORKSPACE" PI_AGENT_NAME="scout1" \
 pi --max-turns 20 --print 'Read plan.md and execute.') &

Architecture

Each agent has its own isolated git repository:

workspace/
├── manifest.json                 ← Agent registry
└── agents/
    ├── scout1/
    │   ├── .git/                 ← Agent's OWN repo (isolated)
    │   ├── audit.jsonl           ← Real-time log
    │   └── output/               ← Work output
    └── scout2/
        ├── .git/                 ← Completely isolated
        └── ...

Benefits:

• Zero lock conflicts between parallel agents
• Turn-level commits (~10x fewer than per-tool)
• Clean separation: audit.jsonl for observability, git for checkpoints

Links

• npm: https://www.npmjs.com/package/pi-shadow-git
• GitHub: https://github.com/EmZod/pi-subagent-with-logging
• Releases: https://github.com/EmZod/pi-subagent-with-logging/releases

License

MIT