Pilot Inspector

A silent sidecar governance agent for Pi — audits workflow, prompt health, and context hygiene at compaction boundaries.

What It Does

Pilot Inspector runs as an invisible sidecar to your Pi coding agent session. Every time Pi prepares for context compaction (when your conversation gets long), Inspector:

1. Audits the full conversation for prompt health, workflow efficiency, and context retention risks
2. Scores each dimension (0–100%) and produces structured findings
3. Generates patch proposals for improvements (AGENTS.md updates, new skills, etc.)
4. Auto-applies safe patches with verification and rollback
5. Injects critical context anchors before compaction to prevent information loss
6. Detects trends across sessions and generates persistent rules
7. Identifies repetitive workflows that could become reusable skills

Quick Start

# Install globally
pi install npm:@skkac/pilot-inspector

# Or install for current project only
pi install -l npm:@skkac/pilot-inspector

That's it. Inspector activates automatically on every compaction boundary.

Commands

Once installed, use these slash commands in any Pi session:

| Command | Description | |---------|-------------| | /inspector | Show latest inspection report | | /inspector list | List all saved reports | | /inspector status | Show statistics & configuration | | /inspector pending | List pending patch proposals | | /inspector review | Interactive review of patches | | /inspector apply <id> | Apply a specific patch | | /inspector reject <id> | Reject a patch | | /inspector auto on\|off | Toggle low-risk auto-apply | | /inspector trends | Cross-session trend analysis (P4A) | | /inspector skills | Detected skill proposals (P4B) | | /inspector guard | Compaction guard status (P4C) |

Architecture

pilot-inspector/
├── index.ts            Entry point, events, commands, orchestrator (1058 lines)
├── types.ts            All type definitions (403 lines)
├── policy.ts           Permission policy, model resolution (235 lines)
├── context-extractor.ts Session snapshot extraction (253 lines)
├── inspector-agent.ts  LLM-powered analysis engine (633 lines)
├── reporter.ts         Report persistence & display (312 lines)
├── patch-planner.ts    Patch proposal enrichment (354 lines)
├── patch-applier.ts    Safe apply + verify + rollback (482 lines)
├── compaction-guard.ts Context anchor injection [P4C] (298 lines)
├── trend-analyzer.ts   Cross-session pattern aggregation [P4A] (371 lines)
└── skill-generator.ts  Repetitive workflow → SKILL.md [P4B] (377 lines)

Total: ~4,800 lines of TypeScript across 11 modules

Phases

Phase 1 — Observation Only

• Extracts read-only context snapshot before compaction
• LLM-powered analysis with structured JSON output
• Scores: prompt health, workflow efficiency, context retention, risk
• Persists reports to .pi/inspector/reports/

Phase 2 — Patch Generation

• Converts findings into concrete patch proposals with diffs/content
• Persists to .pi/inspector/pending/ for review
• Interactive /inspector review workflow

Phase 3 — Auto-Apply (Opt-in)

• Low-risk patches auto-applied with post-verification (5 checks)
• Automatic rollback on verification failure
• Safety gates: risk cap, evidence threshold, session cap, content requirement
• Master switch off by default (/inspector auto on to enable)

Phase 4 — Intelligence Layer

• 4C Compaction Guard: Injects critical context anchors before compression
• 4A Trend Analysis: Detects converging patterns across sessions, generates rules
• 4B Skill Generator: Identifies repetitive workflows → auto-generates SKILL.md

Data Produced

All data lives under your project's .pi/inspector/ directory:

.pi/inspector/
├── reports/           Inspection reports (JSON)
├── pending/           Pending patch proposals
├── backups/           File backups before modification
├── generated-rules.json  Auto-generated rules from trends
└── audit-log.jsonl   Complete audit trail
## Configuration

Inspector uses sensible defaults but is fully configurable via the `InspectorPolicy` interface:

- **Mode**: `observe_only` | `suggest` | `auto_low_risk`
- **Model**: Uses same model as main session by default
- **Triggers**: `before_compact`, `compact`, or both
- **Auto-apply**: Configurable max risk level, session cap, line limits
- **Write policy**: Glob-based allow/deny lists for targets

## Security Model

- **Read-only by default**: Phase 1 never writes outside `.pi/inspector/`
- **Managed blocks**: All AGENTS.md modifications in `<!-- pilot-inspector:start -->` markers
- **Backup before every write**: All modifications create `.bak` files
- **Line count limits**: Default max 40 lines changed per patch
- **Session cap**: Max 3 auto-applies per session
- **Opt-in auto-apply**: Must explicitly enable with `/inspector auto on`
- **Rollback on failure**: Post-apply verification with automatic restore

## Requirements

- [Pi](https://github.com/earendil/pi) >= 2025.x
- Node.js >= 18

## License

MIT