PAEM
Open-source Agent Skill · MIT license

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
View on GitHub

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.

  1. Load

    A new session reads the project summary, task list and latest checkpoint from .paem/.

  2. Verify

    Before trusting anything, it checks the checkpoint still matches the code: HEAD, index and working files.

  3. Work in small steps

    One task at a time, with a checkpoint after every milestone, not just before a likely stop.

  4. 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.

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.

AgentWhere PAEM goesStatus
Claude Code.claude/skills/paem/Tested
Claude.ai / Claude Desktop chatUploaded skill zipTested
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 agentLoad SKILL.md and paem.mdManual

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