Packwright: build a coding-agent pack around how you work — then carry it across runtimes

[pioneerjeff]

Every time I tried a new coding tool, I rebuilt my agent by hand. Same job, same rules, same memory layout, typed again into another file format — and always a little worse than the copy before. After the third rebuild I stopped trusting my own hands for this.

Packwright is what I built instead. It is a Python CLI. You describe the agent once, in plain files: its job, skills, working rules, memory, workspace. Packwright compiles that into a native pack for Pi, Codex, Claude Code, or Cursor — and when you move, it reports what the destination runtime can't carry, before it writes anything.

First: create an agent pack that can do useful work

The shortest interface is a conversation. Install Packwright, hand the operating prompt to your coding agent, and describe the agent you want:

python -m pip install packwright

• Agent operating prompt: https://github.com/pioneerjeff-labs/packwright/blob/main/docs/USE_WITH_YOUR_AGENT.md
• CLI quickstart: https://github.com/pioneerjeff-labs/packwright#readme

Your coding agent drafts a definition for you to review: responsibilities, skills, boundaries, memory behavior, workspace rules. After you confirm, Packwright builds the runtime's native files, installs them, and runs the structural check.

You can also drive the CLI directly. presets prints the exact defaults a starter template ships with, so you can read what you are getting before you use it:

packwright presets code
packwright init --template code --name Nova --user-name Morgan -o work/nova
packwright build work/nova --adapter codex -o pack/nova-codex
packwright install pack/nova-codex --adapter codex --target project/nova-codex

(Nova is an example. Pick your own name.)

A pack is useful before it ever moves anywhere. The agent gets a stable job, native procedures for its runtime, and a working structure made of files you can open in an editor and keep in git.

Then: protect what the agent accumulates

Once an agent becomes useful, it starts to accumulate working state — memory, decisions, drafts. Moving that by hand is where I lost things.

When I first moved my Codex agent into Cursor, the target looked healthy. Rules loaded, memory and workspace were present, the structural check passed. Then I found that memory/index.md still pointed to AGENTS.md, a Codex file that does not exist in a Cursor project. Nothing crashed. The route was simply wrong.

migrate exists to catch exactly this before anything is written. This previews the same kind of Codex-to-Cursor move:

packwright migrate project/nova-codex \
  --to cursor \
  --target project/nova-cursor \
  --dry-run

Here is the receipt from a real run of that command:

Packwright migration planned: codex -> cursor
  project/nova-codex -> project/nova-cursor
  generated: 53 | .cursor/** (20 files) | .packwright/** (30 files) | manifest.json | scripts/** (2 files)
  carried: 24 | knowledge/** (2 files) | memory/** (11 files) | sources/** (4 files) | workspace/** (7 files)
  rewritten: 2 | memory/index.md, memory/pinned.md
  degraded: 0 | none
  excluded: 50 | .agents/** (1 files) | .codex/** (17 files) | .packwright/** (30 files) | AGENTS.md | manifest.json
  score: planned 100.0 (pass)
No files written. Use --json for the complete path-level receipt.

The two entries under rewritten are the same kind of routing lines as my old mistake. Packwright manages those, so it rewrites them for the destination and shows you that it did. The five sections:

• generated — files compiled fresh for the destination runtime
• carried — your own files under memory/, workspace/, knowledge/, and sources/, copied with per-file SHA-256 verification
• rewritten — Packwright-managed routing lines, adapted for the destination
• degraded — behavior the destination cannot reproduce without your explicit acceptance
• excluded — runtime-specific files deliberately left behind

To apply the move, run the same command with --yes. Afterwards, doctor checks the installed project for drift, and score grades the structure.

Pi is the newest target — the rules stay the same

Packwright 0.3 adds Pi Core as the fourth adapter, next to Codex, Claude Code, and Cursor.

A Pi target uses Pi's native project shape:

• AGENTS.md for project context
• .agents/skills/**/SKILL.md for project Agent Skills
• .pi/<name>/references/** for Packwright-scoped references

Two boundaries worth stating plainly. Pi asks for your project-trust decision before project skills load, and Packwright does not try to get around that. Pi can also express lifecycle behavior through executable extensions — Packwright does not generate executable extension code. When canonical behavior cannot run in Pi Core, the receipt marks it degraded, and --yes alone refuses to move:

migration not applied: review degraded runtime automation and rerun with --yes --accept-degraded

That line is from a real run too. Accepting a named gap is a separate decision, and the receipt keeps the record.

The rule is the same for every adapter: emit native files where the runtime has a native surface, and name the gap where it does not.

What a 100.0 score does and does not mean

The receipt above ends with score: planned 100.0 (pass). A tool that grades its own output deserves some suspicion, so here is what that number covers.

The broken target in my story had passed its structural check too. That is why 0.3 stopped compressing everything into one number: score reports the structural result plus a separate readiness report that names what it did not check. Real output, trimmed:

"structural_integrity": {
  "message": "canonical mechanism and generated adapter artifacts were scored",
  "status": "passed"
},
"runtime_activation": {
  "message": "score does not verify runtime trust, reloads, hooks, or extensions",
  "status": "not_evaluated"
},
...
"message": "structural score passed; operational readiness was not evaluated",
"operational_ready": null

So 100.0 means the generated structure passed. Runtime trust, environment bindings, portable-state content, and your end-to-end workflow are named as not evaluated — those you confirm by running the agent on real work once before you rely on it.

What Packwright does not promise

It does not move chat history or provider-side memory. It does not run models, and a structural score is not a promise that different models or runtimes will behave the same. It is not a standard either — it is a portable format and toolchain: four tested adapters, receipts you can diff, plain local files.

On privacy, quoting the README as-is:

Packwright itself makes no network requests and sends no telemetry. Your coding runtime may still send files it reads to its own model provider; its data policy continues to apply.

Where it is now

The current release is 0.3.0 on PyPI, Python 3.9 or newer, MIT-licensed. I have been using it for my own agents and invited a few people, including colleagues, to try it. No major blocker so far, so I am opening it up for wider feedback instead of keeping it private longer. It is still rough in places — some output reads like it was written for me, not for you.

• Repository: https://github.com/pioneerjeff-labs/packwright
• Live guide: https://pioneerjeff-labs.github.io/packwright/
• Pi adapter boundary: https://github.com/pioneerjeff-labs/packwright/blob/main/docs/PI.md
• PyPI: https://pypi.org/project/packwright/

What would an agent pack have to hold — and what would have to survive a move to another runtime — before it is useful for your real work?

Unexpected receipt classifications, missing boundaries, and awkward first-run steps are all useful feedback.

I'm in UTC+8, so replies may pause during my night. I will follow up when I'm back.

[pioneerjeff]

Update — 0.3.1 is now the current stable release.

The Codex → Cursor receipt in the original post was generated on 0.3.0. On a fresh 0.3.1 run, the same migration now reports Cursor’s prompt-time context gap explicitly:

Packwright migration planned: codex -> cursor
  generated: 53
  carried: 24
  rewritten: 2 | memory/index.md, memory/pinned.md
  degraded: 1 | automation:user-prompt-current-todos (user_prompt -> add_context)
  excluded: 50
  score: planned 100.0 (pass)
No files written.

Applying that move requires an explicit degraded-behavior decision:

packwright migrate project/nova-codex \
  --to cursor \
  --target project/nova-cursor \
  --yes --accept-degraded

This is intentional: Cursor can project session-start context, but it cannot reproduce the canonical prompt-time context injection, so --yes alone refuses the move.

Release and full notes: https://github.com/pioneerjeff-labs/packwright/releases/tag/v0.3.1