Workflows

The Quick Start shows the commands. This page shows how to fit them into real work so that keeping the session up to date takes almost no effort.

Your First Session

One rule explains when to run what: agents read their instruction file (CLAUDE.md, AGENTS.md, GEMINI.md) once, when a session starts. So export before you launch an agent.

Set up first, then start the agent

$ cd my-project
$ pas-agent init --task "Add Stripe billing"
$ pas-agent export --to claude    # writes CLAUDE.md
$ claude                          # starts already knowing the task

Or start from inside a running agent

pas-agent is an ordinary command, so the agent can create the session itself. Type this in the chat:

Run pas-agent init --task "Add Stripe billing" and keep the session updated with pas-agent update as you work.

If you exported while an agent was already running

It won't notice the new file on its own. Restart the agent (most reliable), or tell it:"read AGENTS.md and continue the task from the PAS-Agent session context".

Let the Agent Keep the Session Up to Date

pas-agent is an ordinary command, so any coding agent that can run shell commands can update the session itself. You don't have to type update by hand. Tell the agent once, in the instruction file it already reads, and it records its own progress.

Add a section like this to your own part of CLAUDE.md,AGENTS.md, or GEMINI.md, outside the PAS-Agent block, so exports never overwrite it:

## Session handoff (PAS-Agent)

This project tracks work in progress with PAS-Agent.

- When you finish a piece of work, record it:
  pas-agent update --completed "<what you did>" --next "<the next step>"
- Record decisions and why with --decision, open problems with --blocker,
  and newly found work with --remaining.
- At a milestone, or before the session ends, save a checkpoint:
  pas-agent checkpoint "<one-line summary>"
- Run pas-agent status to see the task and the numbered lists.
  Mark remaining item N as done with: pas-agent update --done N

Most agents follow instructions like these. You can also just ask at the end of a session:"record what you did with pas-agent and save a checkpoint".

Automatic updates without any instructions (shell hooks and an MCP server) are coming next. Until then, this instruction is the easiest way to keep the session current.

Switch Agents Mid-Task

The main use case: you hit a usage limit, want a second opinion, or another agent is better at the next step.

1. Ask the current agent to record its progress and save a checkpoint (or run the commands yourself).
2. Export for the next agent: pas-agent export --to codex.
3. Start the next agent in the same project. It reads the exported file at startup.
4. Tell it to continue, for example "continue the task in the PAS-Agent session context".

$ pas-agent checkpoint "Login flow done, refresh tokens next"
$ pas-agent export --to codex
$ codex

Resume the Same Agent Later

A fresh session of the same agent starts with no memory too: the next morning, after the conversation got too long, or after /clear. Export to that agent before you start again:

$ pas-agent export --to claude
$ claude

When to Checkpoint

update changes the current state. checkpoint adds a dated entry to the history, with the git state and changed files at that moment. Good times to checkpoint:

• A piece of work is finished, even if it isn't committed yet
• Right before you switch agents or stop for the day
• Before a risky change, so the history shows where things stood

Checkpoints are cheap. Exports include only the latest 10, so taking many does no harm.

Keep the Lists Tidy

Items are numbered in pas-agent status. Use the numbers to change them:

$ pas-agent update --done 2              # remaining #2 → completed
$ pas-agent update --resolve 1           # drop blocker #1
$ pas-agent remove decisions 3           # delete decision #3
$ pas-agent update --next "Write tests"  # replace the next action

A short, current session helps the next agent more than a long one full of stale items.

Solo or Team: Commit the Session?

The exported block in CLAUDE.md or AGENTS.md can always be regenerated from the session, so it's fine to leave it uncommitted or to commit it.