Panopticon — Automated Project Documentation Registry

Overview

Panopticon is a nightly batch system that maintains up-to-date, LLM-optimized project documentation as pi skill files. It analyzes git diffs since the last run, dispatches parallel LLM workers to update documentation sections, synthesizes the results, and writes pi-compatible skill directories into each project's .pi/skills/panopticon/ folder.

Architecture

CLI entry point: src/index.ts — handles --full-analysis <name>, --project <name>, --dry-run
Config: src/config.ts — loads config.json with project registry, model config, limits
Git: src/git.ts — git operations (pull, diff, log, file tree, churn)
Structural: src/structural.ts — regex-based AST extraction, import graph, file hashing
Session: src/session.ts — pi SDK session factory for orchestrator/worker/synthesizer roles
Orchestrator: src/orchestrator.ts — analyzes diffs, plans work units
Worker: src/worker.ts — generates/updates doc sections with read tool access
Synthesizer: src/synthesizer.ts — reconciles worker outputs, generates SKILL.md
Writer: src/writer.ts — writes skill files to <project>/.pi/skills/panopticon/
Reporter: src/reporter.ts — generates run reports, detects anomalies
Metrics: src/metrics.ts — pushes Prometheus metrics to Victoria Metrics
State: src/state.ts — per-project state persistence (last SHA, file hashes)
Types: src/types.ts — shared type definitions

Key Conventions

All pi SDK sessions are created via createSession() in session.ts
Workers get read-only tools; orchestrator and synthesizer get no tools
Prompts live in prompts/ directory as standalone markdown files
Config is in config.json at project root
State persisted in state/ directory, run reports in runs/

Build & Run

npm run build          # Compile TypeScript
npm start              # Run incremental (all projects)
node dist/index.js --full-analysis snow_trail_sdl   # Full analysis
node dist/index.js --dry-run                         # Test without writing

Dependencies

@mariozechner/pi-coding-agent — pi SDK for LLM sessions
@mariozechner/pi-ai — model resolution and streaming
Node.js 20+, TypeScript 5.7+

2.3 KiB Raw Permalink Blame History