AI sessions end. Your progress doesn't.
PAEM checkpoints long-running coding work into your repository. When a rate limit, a full context window or a crash ends a session, the next one, in any agent, resumes from the last verified state instead of starting over.
npx skills add soyames/PAEM-skill
Tested in Claude Code, Codex CLI and Gemini CLI One shared folder, read by 9 agents No daemon, account or telemetry
The problem
Every long task eventually hits this.
You've reached your usage limit.
The plan lived in the chat
Decisions, trade-offs and the task breakdown disappear with the conversation that held them.
Nobody knows where it stopped
Half-applied edits, tests that may or may not pass, work that might already be done.
The next session starts from zero
Twenty minutes of re-explaining, and a real risk of redoing or undoing finished work.
How it works
Sessions are temporary workers. The repo is the memory.
PAEM is a protocol your agent follows, plus optional Python scripts that make it reliable.
State lives in plain files under .paem/ in your project, so any agent can pick it up.
- checkpoint-012
- checkpoint-013
- checkpoint-014
Load
A new session reads the project summary, task list and latest checkpoint from
.paem/.Verify
Before trusting anything, it checks the checkpoint still matches the code: HEAD, index and working files.
Work in small steps
One task at a time, with a checkpoint after every milestone, not just before a likely stop.
Resume anywhere
When a session dies, open any agent on the same repo and continue from one clear next action.
It knows when a checkpoint has gone stale
Each checkpoint is bound to the Git state it describes. check tells a
resuming session whether the record still describes this code, before it acts on it.
- current
Record, pointer and resume text agree, and the repo still matches.
- stale
Valid record, but the code moved on. Re-verify before continuing.
- inconsistent
Saved files disagree, or a save was interrupted. Stop and report.
- invalid / legacy
Malformed, or written by hand. Never silently trusted as current.
$ python <skill-dir>/scripts/paem_checkpoint.py check --target .
{ "status": "current", ... }
$ git commit -qam "finish login form"
$ python <skill-dir>/scripts/paem_checkpoint.py check --target .
{
"status": "stale",
"reasons": [
"Repository/worktree, HEAD, index or working files
differ from the checkpoint"
]
}
What you get
Small, boring, and dependable on purpose.
Repository-bound checkpoints
Each record carries a fingerprint of the Git state it was written against.
Safe with parallel sessions
A save names the checkpoint it expects. If another session published first, it is refused, not overwritten.
Plain files, any agent
Markdown and JSON in .paem/: readable, diffable, committable, and not tied to one vendor.
Resume prompts that name the exact save
resume_prompt.md is paste-ready for a fresh session and points at one specific checkpoint.
Optional stop-hook guard
On Claude Code, a fail-open hook stops a turn that would end with stale state. Codex, Gemini CLI and Cursor adapters are best-effort.
Nothing to host or trust
No daemon, no account, no telemetry. Without Python, the agent follows the same protocol by hand.
Install
One folder with a SKILL.md. Installs like any skill.
PAEM follows the open Agent Skills format. Most agents now also read
the shared .agents/skills/ folder, so one install usually covers every tool you use.
Any agent
npx skills add soyames/PAEM-skill
Uses the open skills CLI, which asks which agents to install for. It copies only the skill folder.
Bundled installer
git clone https://github.com/soyames/PAEM-skill.git
python PAEM-skill/scripts/install.py --provider agents --scope global # Codex, Gemini CLI, Cursor, Copilot, OpenCode…
python PAEM-skill/scripts/install.py --provider claude-code --scope global # Claude Code
python PAEM-skill/scripts/install.py --list # every provider and path
Python 3.11+, no network. Copies only the runtime files, refuses to overwrite a folder it didn't write, and takes --scope project --target /path/to/app to stay inside one repository.
Gemini CLI
gemini skills install https://github.com/soyames/PAEM-skill --path skills/paem
Gemini CLI's own installer. Project-level skills load only in a folder Gemini trusts.
Claude.ai and Claude Desktop
git clone https://github.com/soyames/PAEM-skill.git
python PAEM-skill/scripts/install.py --zip dist/paem.zip
Then in Claude: Customize > Skills, +, Create skill > Upload a skill, and pick dist/paem.zip. Needs code execution turned on. Chat sandboxes don't persist between conversations, so download .paem/ before you leave; for a real repository, use Claude Code.
Then start a long task
Use PAEM for this project.
Goal: implement user authentication with registration, login and password reset.
Where it works
Tested where we could. Labelled where we couldn't.
"Tested" means a real install was checked in that tool, not just that files landed where its docs say.
| Agent | Where PAEM goes | Status |
|---|---|---|
| Claude Code | .claude/skills/paem/ | Tested |
| Claude.ai / Claude Desktop chat | Uploaded skill zip | Tested |
| Codex CLI | .agents/skills/paem/ | Tested · 0.162.1 |
| Gemini CLI | .agents/skills/paem/ or .gemini/skills/paem/ | Tested · 0.64.0 |
| Cursor | .agents/skills/paem/ or .cursor/skills/paem/ | Documented |
| GitHub Copilot | .agents/skills/paem/ or .github/skills/paem/ | Documented |
| OpenCode | .agents/skills/paem/ or .opencode/skills/paem/ | Documented |
| Devin Desktop (formerly Windsurf), OpenHands, goose | .agents/skills/paem/ | Documented |
| Kiro | .kiro/skills/paem/ | Documented |
| Antigravity | .agents/skills/paem/ | Failed an earlier test |
| Aider, Continue, any file-capable agent | Load SKILL.md and paem.md | Manual |
Codex CLI was checked with codex debug prompt-input, Gemini CLI with gemini skills list. Per-tool guides and exact versions are in the examples and the discovery table in paem.md.
Honest scope
What PAEM doesn't do.
- Recover work that was never checkpointed.A crash between two checkpoints loses that gap. The stop hook narrows it; nothing closes it.
- Enforce anything by itself.Checkpointing is an instruction the agent follows. Hook adapters are best-effort and fail open.
- Predict rate limits.No provider exposes remaining quota, so PAEM checkpoints on milestones instead of waiting for a warning.
- Verify your work.A checkpoint records what the agent claimed, labelled
self_reported. PAEM checks its shape and its binding to the repo.
FAQ
Questions developers ask first.
Is PAEM a service, a daemon or an extension?
None of those. It is an Agent Skill: instructions, templates and optional scripts your agent loads. Nothing runs in the background and nothing leaves your machine.
Do I need Python?
No. Python 3.11+ enables the validated checkpoint writer and the staleness check. Without it, the agent writes the same files by hand and says so.
Where does the state live? Should I commit it?
In .paem/ at your project root. Commit it if teammates or other machines should resume the same work; ignore it if it's just for you. Never put secrets in it.
How is this different from my agent's memory or context compaction?
Built-in memory belongs to one tool and one account. PAEM's state is plain files in the repository, checked against Git before it's trusted, and readable by whichever agent you open next.
Can I switch agents mid-project?
Yes, that's the point. Stop in one agent with a checkpoint, open another on the same clone, and it resumes from the same .paem/. Only one session should write checkpoints at a time.
Does it work in a plain chat with no file access?
Partly. The protocol needs an agent that can read and write files. In a chat without file access you can still paste the resume prompt, but nothing gets saved for you.
Make the next interruption cost minutes, not hours.
Free and open source under the MIT license. Install it once, and every agent you use shares the same project memory.
npx skills add soyames/PAEM-skill