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

``bash


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

`bash


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

$3


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

$3

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

$3

`bash
(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