PrincipalLoop
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
PrincipalLoop
Your coding agent picks up where it left off. PrincipalLoop tells it what changed in between.
Long Codex tasks get interrupted: a chat ends, the context fills up, a teammate or another agent edits the code. When work resumes, the agent trusts a summary, and a summary cannot tell it that retry.py now regenerates the idempotency key the plan relied on.
PrincipalLoop keeps a checkpoint: the files you choose, stored byte for byte, plus a short note from the agent. When anyone comes back, one call compares every tracked file and returns a bounded diff of what changed. No model calls, no network, everything in a local SQLite file outside your repository.
Live demo · Quick start · How it works · What is proven · Roadmap
Quick start
You need uv and Codex (CLI or desktop app). Windows and Linux are tested; --managed-python makes uv use its own Python 3.13, whose SQLite carries the fix the kernel requires.
# 1. Install the command used by the plugin
uv tool install --managed-python git+https://github.com/Venorium/PrincipalLoop
# 2. Add the plugin to Codex
codex plugin marketplace add Venorium/PrincipalLoop
codex plugin add principalloop@principalloop
# 3. In your project, choose the files to track, then check the setup
cd my-project
principalloop codex enable --objective "Make payment retries safe" \
--allow-file src/payments/retry.py --allow-file docs/plan.md
principalloop codex doctorOpen a new Codex chat in that project and ask:
$principalloop Save a checkpoint of this work.
Later, in the same chat or another one:
$principalloop What changed since the checkpoint? Tell me what to re-check before continuing.
No Codex at hand? principalloop demo runs the eight scenarios above and opens the report in your browser.
Related MCP server: Session Handoff MCP
What Codex gets
Tool | What it does |
| Shows whether the project is enabled, the files you allowed and the recent checkpoints |
| Stores the chosen files and a resume note; a lost response can be retried safely with the same ID |
| Compares one checkpoint with the current files and returns |
| Reads the captured version of a file, page by page |
This is what the agent receives after the payment code was edited behind its back:
Review needed: The current file differs from the captured content.
Result: REVIEW_REQUIRED
- src/payments/retry.py: CHANGED
--- checkpoint/src/payments/retry.py
+++ current/src/payments/retry.py
@@ -5,7 +5,6 @@
def retry_charge(client, charge):
- # One idempotency key per charge, reused on every attempt.
- key = charge.idempotency_key
for attempt in range(MAX_ATTEMPTS):
+ key = new_idempotency_key() # regenerated on each attempt
response = client.charge(charge.amount, idempotency_key=key)For you, principalloop codex report opens a private, offline report of the latest checkpoint, with the agent's note and the captured and current versions side by side.
How it works
flowchart LR
H["You: principalloop codex enable<br/>choose files and goal"] --> P[(Private profile)]
C["Codex chat"] -->|"starts the plugin server<br/>in the chat's folder"| M["PrincipalLoop<br/>MCP server"]
P --> M
M -->|checkpoint| K["Deterministic kernel"]
K --> DB[("Local SQLite<br/>outside the repo")]
M -->|"check: bytes and premises"| DB
M -->|"bounded diff"| CA few rules hold everywhere:
Codex identifies the project, not the model. Codex starts the plugin server in the chat's working directory and can attach its sandbox directory to each call. No tool argument can choose a workspace, a role or a file outside your list.
You choose the files. The agent saves and reads checkpoints only within the list you enabled.
A note is a claim, not a fact. It is stored as unverified. Captured content is data, never instructions.
An error is never "unchanged". An unavailable server, a refused call or a missing checkpoint is reported as such.
Your repository stays clean. State lives in
%LOCALAPPDATA%\PrincipalLoopon Windows and$XDG_STATE_HOME/PrincipalLoopon Linux.
Why this exists
The companion is the first usable layer of a research question: does a separate strategic supervisor improve a coding agent's work at equal resources, or does a good self-review do as well? A negative answer is a useful answer.
Testing that requires context you can verify. A director's advice is only as good as the premises it read, so the kernel records every read, binds evidence to captured bytes and refuses to act on a stale snapshot. That same kernel powers checkpoints today. The specification and the experimental protocol describe the comparison: executor alone, executor with self-review, executor with a director, and controls at matched budgets.
What is proven so far
Capability | Evidence |
Kernel: contracts, state machine, SQLite journal, transactions, crash recovery | 199 tests on Windows, 195 on Linux (4 Windows-only recovery tests skipped); processes killed at commit boundaries |
Snapshots and freshness | Eight scenarios executed for real in the demo, including the case the check cannot see |
Codex plugin | Installed from this repository into an isolated Codex home and called through App Server, with Codex 0.166.0 and the 0.167 desktop build, zero model turns (report) |
Not established yet, and said plainly in the report and the docs:
the director itself and its strategic benefit;
the measured benefit of checkpoints on real resumes (a 10-case protocol is ready);
macOS, and any enforcement over Codex's own tools: the integration is COOPERATIVE, so the same OS account can bypass it.
Diagnose
$ principalloop codex doctor
PrincipalLoop 0.1.0 — /home/you/my-project
[ok] Runtime: Python 3.13.16, SQLite 3.53.1: reference runtime.
[ok] Activation: 2 tracked file(s).
[ok] MCP server: Real STDIO exchange, 4 tools, no model call.
[ok] Plugin command: /home/you/.local/bin/principalloop (version 0.1.0).
[ok] Codex: Plugin enabled: principalloop@principalloop. Open a new chat to load its tools.
Ready. In a new Codex chat: $principalloop Save a checkpoint of this work.Each failing line comes with the exact command that fixes it, including the common trap where Codex ignores a project's .codex/config.toml because the project is not trusted.
Roadmap
Status | Step |
Done | Reproducible runtime, pure domain model, persistent journal, verifiable snapshots, visual report |
Done | Codex plugin: MCP server, resume skill, human activation, diagnosis, bounded diffs |
Next | Budget and effect ledger, then single activation with plan epochs (PL-05, PL-06) |
Then | Crash and replay campaign, deterministic demonstrator with an independent oracle (PL-07, PL-08) |
Then | Director in SHADOW mode, one real connector, A/B/C/D comparison (PL-11 to PL-13) |
Details and acceptance criteria: backlog.
Limits
Up to 32 tracked files per project, 1 MiB per file, 8 MiB per checkpoint.
A check compares bytes. A changed comment is a change; a dependency you never tracked stays invisible.
Command messages and reports are in English;
--lang frrenders the reports in French.
Documentation
Read | For |
Install, use, diagnose and uninstall | |
Trust boundaries and what is qualified | |
How the kernel works | |
The research question and how it will be tested | |
Every executed check and what it does not prove | |
Architecture decisions and open questions |
Development
uv sync --locked
uv run python -m pytest -q
uv run python -m principalloop doctor
uv run python scripts/validate_preparation.py
uv run python scripts/qualify_codex.py --output .tools/codex.json # needs Codex installedOn Windows without uv, scripts/bootstrap.ps1 builds the pinned environment. See CONTRIBUTING.md; report vulnerabilities as described in SECURITY.md.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Agent checkpoints. Resume after context resets and handoffs with retry-safe, versioned saves.
Checkpoint and resume for AI agent runs, so crashed runs pick up where they left off.
Evidence-backed project memory and checkpoints for AI coding agents.
Sync coding-agent sessions and resume them in any other agent: Claude Code, Codex, Cursor, more.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceGives AI agents memory, undo, and self-awareness by tracking file changes and enabling checkpoints and rollbacks.83 npm2MIT- AlicenseNot gradedqualityDmaintenancePreserves continuity between coding agent sessions (e.g., Claude Code and Codex) via local, structured checkpoints, enabling a checkpoint → clear → resume workflow.MIT
- AlicenseNot gradedqualityBmaintenanceCaptures checkpoints of project files and SQLite tables before an AI agent makes risky changes, then reports differences and rolls them back byte-for-byte, including dropped tables and agent-created junk. Enables agents to snapshot, diff, list, and restore working state with explicit confirmation required before any destructive action.18 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to record checkpoints for Markdown files and ask what changed since they last looked, returning only the changed Markdown blocks as precise word-level diffs with attribution. Keeps a local, private revision history so multiple readers and writers can each track their own bookmark instead of re-reading whole files.MIT