How vacterro/saipen works
SAIPEN is a local, file-backed continuation protocol for AI coding agents. The principal workflow is to invoke continue, resolve the project’s persisted state and next action, resume work, and checkpoint the result through journaled operations that are validated before and after mutation. Plain project files preserve state, task history, and durable knowledge across sessions. The README also describes optional autonomous maintenance and goal/subagent modes, plus host installation and a canonical validator. Several internal links are based on README statements or SOURCE INDEX references; unsampled behavior is not inferred.
Main entry points: operations.py State operations · router.py Action router · saipen.py SAIPEN CLI · fast_check.py Mutation checks
Components 20
Continuation workflow
- SAIPEN CLI
tools/saipen.py - Action router
tools/saipen_engine/router.py - State operations
tools/saipen_engine/operations.py - Context compiler
tools/saipen_engine/context.py
Project state
- Project memory files
tools/saipen_engine/paths.py - Ticket board
tools/saipen_engine/board.py - State parser
tools/saipen_engine/state.py - Event history
tools/saipen_engine/log.py - Durable knowledge
tools/saipen_engine/context.py - Source intake
tools/saipen_engine/intake.py
Integrity checks
- Write-ahead journal
tools/saipen_engine/journal.py - Document codec
tools/saipen_engine/codec.py - Mutation checks
tools/saipen_engine/fast_check.py - Canonical validator
tools/validate.py - Freshness identity
tools/freshness.py
Optional extensions
- Autonomous maintenance
tools/improve.py - Crew execution
tools/saipen_engine/crew.py - Host integration
tools/autoinject.py - OpenCode guard
extensions/adapters/opencode/saipen-guard.js
Other components
- Operator / agent
Connections 23
- Operator / agent → SAIPEN CLI: invokes
README.md - SAIPEN CLI → Action router: routes actions
tools/saipen.py - SAIPEN CLI → State operations: runs operations
README.md - Action router → State parser: reads state
tools/saipen_engine/router.py - Action router → Ticket board: reads tickets
tools/saipen_engine/router.py - Context compiler → Action router: uses routing
tools/saipen_engine/router.py - Context compiler → Durable knowledge: loads relevant facts
README.md - State operations → Write-ahead journal: journals mutations
tools/saipen_engine/journal.py - State operations → Mutation checks: checks proposals
tools/saipen_engine/fast_check.py - State operations → Project memory files: writes checkpoints
README.md - State operations → Event history: records events
tools/saipen_engine/operations.py - Write-ahead journal → Document codec: preserves bytes
tools/saipen_engine/journal.py - Mutation checks → State parser: validates state
tools/saipen_engine/fast_check.py - Mutation checks → Ticket board: validates tickets
tools/saipen_engine/fast_check.py - Canonical validator → Project memory files: validates checkpoints
README.md - Canonical validator → Freshness identity: checks freshness
- State operations → Source intake: captures source
tools/saipen_engine/operations.py - Autonomous maintenance → Write-ahead journal: uses journal
tools/improve.py - Crew execution → Canonical validator: gates convergence
- Operator / agent → Host integration: installs locally
README.md - Host integration → OpenCode guard: supports host
- Autonomous maintenance → State operations: evolves project
- Operator / agent → Crew execution: opts into execution
README.md