Your coding agent wrote the code. Can you show what it was asked, what it was allowed to touch, and what it actually tested?
MPSF (My Personal Software Factory) is a free plugin for Claude Code and OpenAI Codex that turns agent work into a reviewable, verifiable record kept in your own git repository.
No server, no account, no telemetry: records stay in your repository.
Try it · Why it is different · Several computers · How it compares · Docs
Agents are fast. The problem is everything around the diff: a chat that scrolls away, an assumption nobody confirmed, a file outside the agreed scope, a "tests pass" that was never run. Code review sees the result, not the reasoning or the boundary.
MPSF puts a contract around each piece of agent work:
- Agree first. The agent states what it understood about the project and proposes a plain-language work brief: goal, files, tools, limits, exclusions. You approve it once.
- Work inside the boundary. A deterministic CLI, not the model, checks the work against what you approved. Changed files outside the agreed paths, actions outside the approved set and exhausted budgets stop the delivery.
- Prove it. Tests are recorded with the exact command, exit status and output. "Done" means the gate passed on recorded evidence, not that the agent said so.
- Keep it. Requests, decisions, changes and checks live under
.sdlc/in your repository, travel with the code, and open in a local visual app.
Change Observatory, the bundled local app (sample data). It runs on 127.0.0.1 and never edits your code or your records.
Requires Node.js 18.20.3–18.x, 20.12.0–20.x, or 21.6.0+ and Git.
Type these in the Claude Code prompt, not in a shell:
/plugin marketplace add aantenore/mpsf
/plugin install mpsf@aantenore
/mpsf:doctor
Full guide: Claude Code Installation.
Codex installs from a checkout through a transactional installer (check, plan, apply, validate, with a byte-exact restore if anything fails):
git clone https://github.com/aantenore/mpsf.git
cd mpsf
python3 scripts/install-personal-marketplace-v2.py check
cd ..Then follow Codex install for the remaining steps.
mkdir mpsf-trial && cd mpsf-trial && git initThis local-only trial runs a sandboxed smoke test: built in on macOS and Windows 10 1809+, while Linux needs bubblewrap at /usr/bin/bwrap (sudo apt install bubblewrap or your distribution's package).
Open the folder in a new agent session and ask:
Initialize MPSF in this project with the default workflow.
Then:
Build and verify this result only on my local machine. Do not push, open a pull request, deploy, or use production.
Implement a configurable trip-policy module that rejects trips above a cost limit, with tests.
The agent proposes a requirement and a work brief and waits for your approval before writing code. When it finishes, run /mpsf:observe (or ask it to open the Change Observatory) to see the request, the decisions, the changed files and the recorded tests. Delete the folder to remove everything.
On a real project, start with the request that matches the outcome and add your requirement, PR link or limits after it:
| Goal | Ask the agent | Claude Code shortcut |
|---|---|---|
| Understand an existing codebase | Contextualize this project and prepare an initial technical assessment. |
/mpsf:assess |
| Requirement to a new pull request | Turn this new requirement into an agreed work brief, implement it, verify it, and open a new pull request. |
/mpsf:deliver |
| Finish a pull request that already exists | Continue this existing pull request, verify the requested changes, and update the PR without creating a new one. |
/mpsf:continue-pr |
| Build and verify only on this machine | Build and verify this result only on my local machine. Do not push, open a pull request, deploy, or use production. |
/mpsf:local |
Full walk-through: Getting started. To run the mpsf … commands shown in the docs from your own terminal, see Run the CLI from your terminal.
| What MPSF does | Where to check | |
|---|---|---|
| The model is not the referee | Requirements, work briefs, permissions, budgets and evidence are validated by a deterministic Node.js CLI against JSON schemas. The conversation proposes; the CLI decides what is allowed. | Architecture |
| Autonomy is chosen per delivery | For each pull request or local release you pick how independent the agent is: ask at every step, continue between checkpoints, or finish inside the shown limits. Merge, production, deploy and force-push are never implied. | How it works |
| Evidence, not claims | test record binds a story to the exact command and exit status. The lifecycle gate passes only when requirement, contract, outputs, latest tests and release evidence agree. Changed files are scanned for committed credentials. |
Commands |
| History you can check | The local trace is hash-linked to a checkpoint, so edits, reordering and truncation are detected by mpsf trace verify. That is tamper-evident, and the docs say plainly it is not tamper-proof. |
Self-service CLI |
| Records live in your repo | Everything is plain files under .sdlc/ (or an sdlc-state branch). Another person or agent can pick up the work months later without the original chat. |
Knowledge-base structure |
| Readable by non-engineers | The Change Observatory answers "what was asked, what changed, why was it decided" for each story, down to the raw record. English and Italian UI. | Change Observatory |
| Two hosts, one tree | Claude Code and Codex load the same skills, schemas, templates and CLI. | Hosts |
| Windows included | The local-release smoke test runs in a sandbox on all three systems: built in on macOS, bubblewrap on Linux, a per-run AppContainer on Windows 10 1809+ with no admin rights. | Windows |
Change one word in the recorded history and the next check says so, with exit status 1 (output shortened):
$ mpsf trace verify
The project history changed unexpectedly.
- .sdlc/traces/project.jsonl: CHANGED (checkpoint_drift, last_event_hash_mismatch, rolling_hash_mismatch)
Commit a fake cloud key and the delivery cannot be certified:
$ mpsf secret scan --story ST-001 --base HEAD~1
- Found 2 credential match(es) in 1 scanned file(s) of story ST-001
- src/config.mjs:1 aws_access_key_id AKIA…
Both run in a throwaway folder in one minute: See it catch problems.
Every recorded request, agreement, change, decision and check, filterable by story (sample data).
Run agents on several machines against the same project and coordinate them through the git remote you already have.
flowchart LR
A[Computer A<br/>agent] -- claim ST-002 --> R[(Project git remote<br/>refs only)]
B[Computer B<br/>agent] -- claim ST-002 --> R
R -- accepted --> A
R -- refused: held by A --> B
- Atomic story claims.
story claimrecords the claim on the remote with a push that only the first claimer wins. The other computer is told who holds the story, on which branch and since when. - Signed messages between computers. The default channel is one git ref per computer; each message is a small commit signed with that computer's Ed25519 key. Unregistered or wrong signatures are shown as untrusted. Messages only inform; they never approve or claim anything.
- Agent discussions with a binding outcome. When two agents disagree (who takes a half-finished story, for example) they can open a short, time-boxed discussion. Only a signed, schema-valid decision binds, and it maps to an existing command that still runs all its checks. An unresolved objection goes to a person.
- Optional coordinator role. One computer can hold a lease to merge pull requests one at a time, publish records, free abandoned claims and keep the base branch green.
- Any git server. Claims, the channel, signatures and discussions work on GitHub, GitLab, Gitea/Forgejo, Bitbucket or a bare git remote. Coordinator merges use the GitHub, GitLab and Gitea/Forgejo APIs.
- Mixed plugin versions. A record that needs a newer plugin declares it; an older install keeps read-only commands working and refuses changes until it is updated.
Three computers on one project: who holds which story, an open question, and a discussion that ends in a proposed claim (sample data).
Details: Messages between computers, Adapters and roles, Parallel work.
MPSF does not replace your agent, your tests or your CI. It adds the agreement and the record around them.
| Plain agent session | Rules file (CLAUDE.md, AGENTS.md) |
Spec-driven kit (e.g. Spec Kit) | CI checks | MPSF | |
|---|---|---|---|---|---|
| Scope agreed before the agent writes code | partly | ✔ | ✔ | ||
| Scope enforced outside the model | ✔ | ||||
| Agent autonomy chosen per delivery | ✔ | ||||
| Tests tied to the exact command and exit status that ran | ✔ | ✔ | |||
| Why a decision was taken, kept with the code | partly | ✔ | |||
| Visual history a product owner can read | ✔ | ||||
| Several computers coordinated without a server | ✔ |
A spec-driven kit gives the agent better instructions: spec, plan and task files it reads before coding. MPSF checks the result against what you approved, with a deterministic CLI instead of the model's word. The two fit together: the agent can turn a spec into the requirement you approve.
- Developers using Claude Code or Codex on real repositories, who want to hand over bigger tasks without losing control of scope.
- Software houses that have to show a client what was asked, decided, changed and verified for each delivery.
- Teams in regulated environments that need a change trail they can audit. MPSF keeps evidence; it does not certify compliance on its own.
Do I have to learn the CLI? No. You talk to the agent as usual; the skills load when the conversation matches, and the slash commands are only shortcuts. A few steps are reserved for you in your own terminal, such as approving a standing approval; the agent hands you the exact command.
Can the agent get around it? Partly, and the docs say where. The hooks and the CLI refuse the obvious paths, but in the default mode an agent that writes and runs its own script could still approve a standing approval. Projects that need more turn on signed approvals, where only the host's Ed25519 receipt counts.
What does it cost my session? Each hook check adds a short Node start-up to shell and edit calls, and hook output is capped per event (700 tokens at session start, a few hundred elsewhere). Agents read small per-story context packs instead of whole records.
What if I stop using it? /plugin uninstall mpsf@aantenore. The records stay in .sdlc/ as plain files (JSON, JSONL, Markdown) in your repository, readable without the plugin.
- 1.1.0 — Rolls up 1.0.1–1.0.33: clearer first run and doctor, a polished Change Observatory with a
--demosample, sturdier guard, locks and Windows support, SECURITY.md and CONTRIBUTING.md, CLI did-you-mean. - 1.0.33 — Governance matrix test no longer fails on hosts without a smoke sandbox.
- 1.0.32 — README shows the two checks failing on purpose.
- 1.0.31 — CLI suggests the command or option you meant.
- 1.0.30 — SECURITY.md and CONTRIBUTING.md; docs and skills match the CLI.
Every release is in the changelog.
Issues and pull requests are welcome: see CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md.
MIT © Antonio Antenore