How parnish007/imperium works
Imperium is a local supervisor that mediates between a director or owner and coding agents. Its main workflow queues instructions, polls agent activity to establish delivery and record events, then separates a completion claim from snapshot-based verification and human acceptance. The graph also includes approvals, per-reader feeds, liveness, isolation, notifications, dashboard, and backup capabilities documented in the README. Relationships among unsampled subsystems are included only where documented; source excerpts do not expose every daemon route or runtime call.
Main entry points: journal.py Hash-chain journal · engine.py Polling engine · rounds.py Work rounds · cli.py CLI
Components 25
User interfaces
- CLI
src/imperium/cli.py - Director MCP
src/imperium/director_mcp.py - Read-only dashboard
src/imperium/dashboard/app.js - Notifications
src/imperium/notify.py
Control service
- Local daemon API
src/imperium/daemon.py - API client
src/imperium/client.py - Local transport
src/imperium/transport.py - Bearer tokens
src/imperium/tokens.py
Agent delivery
- Polling engine
src/imperium/engine.py - OpenCode adapter
src/imperium/opencode.py - ACP adapter
src/imperium/acp.py - Message outbox
src/imperium/outbox.py
Evidence and assurance
- Work rounds
src/imperium/rounds.py - Trusted verification
src/imperium/verify.py - Workspace snapshots
src/imperium/snapshot.py - Permission approvals
src/imperium/approvals.py - Agent liveness
src/imperium/liveness.py
Operations
- Hash-chain journal
src/imperium/journal.py - Event feeds
src/imperium/feeds.py - SQLite store
src/imperium/store.py - Backup and restore
src/imperium/backup.py - Event retention
src/imperium/retention.py
Other components
- Director
- Owner
- Coding agent
Connections 29
- Owner → CLI: runs commands
README.md - Director → Director MCP: uses tools
README.md - CLI → Local daemon API: calls API
src/imperium/cli.py - Director MCP → API client: uses client
src/imperium/director_mcp.py - API client → Local transport: sends requests
src/imperium/client.py - API client → Bearer tokens: selects credentials
src/imperium/client.py - Owner → Read-only dashboard: views status
README.md - Owner → Notifications: receives alerts
README.md - Local daemon API → Polling engine: runs supervision
README.md - Polling engine → OpenCode adapter: polls and dispatches
src/imperium/engine.py - Polling engine → ACP adapter: polls and dispatches
src/imperium/engine.py - Coding agent → OpenCode adapter: serves HTTP
README.md - Coding agent → ACP adapter: speaks ACP
README.md - Polling engine → Message outbox: delivers queued work
src/imperium/engine.py - CLI → Work rounds: manages rounds
README.md - Work rounds → Message outbox: queues round messages
src/imperium/rounds.py - Work rounds → Trusted verification: requests checks
README.md - Trusted verification → Workspace snapshots: checks snapshot
src/imperium/verify.py - Local daemon API → Permission approvals: handles approvals
src/imperium/daemon.py - Polling engine → Agent liveness: reports activity
src/imperium/engine.py - Polling engine → Hash-chain journal: records observations
README.md - Message outbox → Hash-chain journal: records transitions
src/imperium/outbox.py - Work rounds → Hash-chain journal: records round events
src/imperium/rounds.py - Permission approvals → Hash-chain journal: records decisions
src/imperium/approvals.py - Hash-chain journal → SQLite store: persists events
src/imperium/journal.py - Event feeds → Hash-chain journal: reads events
src/imperium/feeds.py - Notifications → Event feeds: reads feed
src/imperium/notify.py - Backup and restore → SQLite store: backs up database
src/imperium/backup.py - Event retention → Hash-chain journal: prunes events
src/imperium/retention.py