Portable State

Portable state is how PAS-Agent moves a session between agents. It turns the session into Markdown and writes it into the instruction file each agent already loads at startup.

Which File Each Agent Reads

Files are written to the project root unless you pass --output.

Your Existing Instructions Are Kept

Many projects already have a hand-written CLAUDE.md or AGENTS.md. PAS-Agent never replaces it. The export goes inside a marked block:

# Team rules            ← your content, untouched
Never push to main.

<!-- pas-agent:start (generated by `pas-agent export`; ...) -->
# PAS-Agent Session Context
...
<!-- pas-agent:end -->

• If the file doesn't exist, it's created with just the block.
• If it exists without a block, the block is appended to the end.
• If it already has a block, only that block is replaced.
• --force replaces the whole file.

If the file has a start marker without an end marker, or the other way round, the export stops and changes nothing.

Generated Context

# PAS-Agent Session Context

This context was exported by PAS-Agent so you can continue work from a previous session. ...

## Project
- **Name:** my-project
- **Session ID:** 46d89609-104d-4a43-907d-dbca99704a85
- **Created:** 2026-09-17 04:30 UTC
- **Updated:** 2026-09-17 04:39 UTC

## Task
Implement user authentication with JWT

## Completed Work
- Created login endpoint

## Remaining Work
- Add token refresh

## Next Action
Implement token refresh endpoint

## Decisions Made
- Use bcrypt for hashing

## Git State
- **Branch:** main
- **Commit:** abc1234d
- **Uncommitted changes:** yes

## Files Changed (as of last checkpoint)
- `src/auth/mod.rs` (modified)

## Checkpoint History
- **2026-09-17 04:35 UTC** — Implemented login endpoint

---
*Exported by PAS-Agent v0.2.1*

Git state is refreshed on every export. The history is limited to the latest 10 checkpoints and 50 changed files, so the file stays within the size limits some agents enforce.

Trust Model

Whatever is in the session ends up in a file your agent treats as instructions. If you commit .pas-agent/ or accept it from other people, review changes to it the same way you'd review changes to CLAUDE.md or AGENTS.md.

To limit accidental or malicious formatting, every value is exported as a single line. Newlines are collapsed, a leading # is escaped so it can't start a heading, and HTML comment openers are neutralised so they can't fake the block markers. The export also tells the agent to follow the project's own instructions if they conflict with it.

Export Command

# For Codex / OpenCode / Cursor / Kiro CLI / Antigravity
pas-agent export --to codex

# For Claude Code
pas-agent export --to claude-code

# For Gemini CLI
pas-agent export --to gemini-cli

# Custom output path
pas-agent export --to codex --output ./handoff.md

# Replace the whole file instead of only the PAS-Agent block
pas-agent export --to codex --force