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