packwright 0.3.0

Build, install, and migrate portable agent packs across Codex, Claude Code, Cursor, and Pi.

Packwright

Build your agent once. Carry it everywhere.

Compile one agent definition—rules, memory, skills, and workspace—into native packs
for Codex, Claude Code, Cursor, and Pi. Build, install, migrate, and verify with plain files.

Explore the live product website →
Watch the animated CLI, follow a Claude Code → Codex migration, and start with Pi, Codex, Claude Code, or Cursor.
English · 简体中文

Native packs. Portable state. Preview every migration before any files are written.

[!TIP] New in 0.3.0: Pi Core support. Build native AGENTS.md and project Agent Skills for Pi, or migrate portable state to and from Pi with explicit capability-gap receipts.

[!NOTE] 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.

Start with your coding agent

The shortest interface is a conversation. Install Packwright, then paste the operating prompt into Codex, Claude Code, Cursor, or Pi:

python -m pip install packwright==0.3.0

Open the paste-ready agent prompt →

For a new agent, describe what it should do and choose its name. The prompt makes your coding agent draft a canonical intake, confirm it with you, build the pack, and verify the installed target. For migration, it previews the receipt and waits for approval before writing.

Create your own

Generate Packwright's interviewer contract, then let your coding agent turn the conversation into a confirmed character_intake.yaml:

packwright draft-character \
  --user-name Morgan \
  --prompt-out work/character-interviewer.md

After the agent saves the confirmed intake, create editable source and build it:

packwright init work/nova-intake.yaml -o work/nova
packwright build work/nova --adapter claude-code -o pack/nova-claude
packwright install pack/nova-claude --adapter claude-code --target project/nova-claude

Already have an agent or workspace? Inventory it before importing anything:

packwright adopt --from existing-agent --dry-run

To create review materials, add --target <target-dir>. Packwright writes a source-scoped adoption-review-<source>-<hash>.yaml queue with every decision set to pending, so multiple source inventories do not overwrite one another. Review items individually, preview with packwright adopt --review <queue> --target-dir <target> --dry-run, then replace --dry-run with --yes. Approved safe copies and source registrations can be applied; memory merge and knowledge promotion remain manual.

Without a coding agent, packwright init --interactive offers a fixed-question fallback. It shows the completed canonical YAML and waits for confirmation before writing.

Or use a nameless starter

Three presets cover common starting points. Customize responsibilities, capabilities, voice, boundaries, and emotional feedback; the preset shapes how the agent works, while you always choose its name.

Preset	Starting role
code	Expert engineer — builds, reviews, debugs, tests, and ships technical work
work	Versatile assistant — plans projects, drafts deliverables, clarifies decisions, and keeps execution moving
companion	Personal secretary — supports daily routines, life decisions, travel planning, and emotional support

Inspect the exact defaults, choose a preset, and supply the character name yourself. Preset-based init returns the full character summary for review before build.

If you already have a confirmed intake, packwright new can run init, build, and install together without discarding the intermediate source or pack:

packwright new work/nova-intake.yaml --adapter claude-code \
  --work-dir work/nova --pack-dir pack/nova-claude \
  --target project/nova-claude

It is fresh-path only: work, pack, and target must not already exist or overlap. Preset use requires an explicit --accept-preset assertion after review.

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

Compiler-owned boilerplate supports English and Simplified Chinese. Put locale: zh-CN in a CharacterIntake, or pass --locale zh-CN with a preset. English is the deterministic fallback for missing or unsupported values; Packwright leaves user-authored prose unchanged.

Nova is only an example of a user-chosen name. Edit the generated name, relationship, voice, and boundaries whenever you need.

Preview a move from Claude Code to Codex. The destination is not created during this step:

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

The plan names five kinds of paths:

Receipt section	Meaning
generated	Files compiled for the destination runtime
carried	Portable user files copied and SHA-256 verified
rewritten	Packwright-managed routing lines changed for the destination
degraded	Unmanaged source automation or a destination capability gap that requires explicit acceptance
excluded	Runtime-specific files deliberately left behind

After reviewing the receipt, apply that exact move and verify the result:

packwright migrate project/nova-claude \
  --to codex \
  --target project/nova-codex --yes
packwright doctor project/nova-codex
packwright score project/nova-codex

Upgrade the mechanism of one installed local instance separately from work handoff or cross-runtime migration:

packwright reconcile --target project/nova-codex --mechanism work/nova --json --dry-run
packwright reconcile --target project/nova-codex --mechanism work/nova --json --yes

Mechanism 0.8 projects bounded local session_start and user_prompt context from canonical automations. Claude Code and Codex support both events. Cursor supports session-start context but reports prompt-time context as an explicit capability gap. Pi Core reports both events as requiring a separately reviewed project extension; it does not generate executable extension code. Existing user settings and hook entries are preserved by entry-level managed merges.

Add --json to the dry run and confirmed run for a machine-readable packwright-migration/v1 receipt. Packwright refuses to overwrite an existing target unless you separately opt into --force.

Why not just prompts?

A working coding agent is more than its top-level instructions, and each runtime expects a different native layout:

Runtime	Native entry	Reusable procedures
Codex	AGENTS.md	.agents/skills/<name>/SKILL.md
Claude Code	CLAUDE.md	.claude/skills/<name>/SKILL.md
Cursor	.cursor/rules/<name>.mdc	.cursor/rules/<name>-save-context.mdc
Pi	AGENTS.md	.agents/skills/<name>/SKILL.md

Packwright treats those files as compiled projections. Your editable source owns the behavior; adapters own the runtime layout; migration carries portable state and reports the seams instead of hiding them.

Build once, carry everywhere

editable source
  identity · memory contract · skills · workspace rules
         │
         ├── packwright build --adapter codex       → AGENTS.md + .agents/skills/
         ├── packwright build --adapter claude-code → CLAUDE.md + .claude/skills/
         ├── packwright build --adapter cursor      → .cursor/rules/*.mdc
         └── packwright build --adapter pi          → AGENTS.md + .agents/skills/ + .pi/<name>/references/

Every pack and installed target includes self-contained .packwright/ metadata: an embedded source snapshot, artifact lock, and checker receipt. You can relocate a target and still run migrate, doctor, and score without its original build directory. Edit the canonical source in the work directory, not the installed target or .packwright/source; reconcile refreshes the embedded snapshot and managed projections from that work directory.

Move a working agent

migrate recompiles runtime-native files and carries portable state into the destination. It reports what cannot carry before it writes, then waits for an explicit --yes. The receipt is the proof behind “carry it everywhere,” not a promise that unlike runtimes have no seams.

What the checks prove

• score evaluates the public pack structure and artifact contract. 100.0 is a structural pass, not a runtime-ready claim. Its machine-readable readiness block marks portable state, activation, bindings, and workflow acceptance as not_evaluated.
• doctor verifies Packwright-managed projection hashes and can repair reproducible drift without treating portable user state as generated output. It separately reports readiness.operational_ready, including Pi trust, canonical automation gaps, and pending adoption-review items.
• Migration verifies carried and rewritten files in the destination, rechecks detected degraded source files before writing, records planned and installed scores, and never silently treats runtime automation as portable. When degraded items exist, non-interactive apply also requires --accept-degraded.
• Reconcile compares installed and desired canonical spec hashes, preserves instance state, and writes a local receipt without reverse-compiling another runtime's hooks.
• The release gate exercises all 12 directed migration paths across Codex, Claude Code, Cursor, and Pi. Pi destinations require explicit acceptance of canonical automation gaps.

Current release boundary

0.3.0 is the current stable release and the first release with Pi Core support; 0.1.0 remains the first stable baseline. Packwright is local tooling, not cloud sync, and its plain-file structure score is separate from real runtime compatibility. Pi project trust and lifecycle extensions remain explicit runtime activation steps rather than generated claims.

Documentation

• Live product website · 简体中文
• CLI contract
• Use Packwright with your coding agent
• Character drafting
• Agent archetypes
• Optional Emotion Engine MCP runtime
• Pi Core adapter
• Local runtime automations
• 0.3.0 release notes
• 0.2.0 release notes
• 0.1.2 release notes
• 0.1.1 release notes
• 0.1.0 release notes
• Contributing
• Security

Packwright is open source under the MIT License.