Quick Start

This guide walks through the basic PAS-Agent workflow: initialize a session, record progress, and export context for another agent.

1. Initialize a Session

Run init anywhere inside your project. Inside a git repository, the session is created at the repository root:

$ cd my-project
$ pas-agent init --task "Implement user authentication"
PAS-Agent session initialized.
  Project: my-project
  Session: 46d89609-104d-4a43-907d-dbca99704a85
  Store:   /home/me/my-project/.pas-agent/session.json
  Git:     main @ abc1234d

Tip: commit .pas-agent/ to carry the session across machines, or add it to .gitignore to keep it local.

This creates .pas-agent/session.json. Every other command finds it from any subdirectory of the project.

2. Update Session State

As you work, record progress. List flags can be repeated, and each value is one item, so items can contain commas:

$ pas-agent update \
    --completed "Created login endpoint" \
    --completed "Added password hashing" \
    --remaining "Add token refresh" \
    --remaining "Write tests" \
    --next "Implement token refresh endpoint" \
    --decision "Use bcrypt, not argon2, to match the legacy service"

When a remaining item is finished, mark it done by its number from status:

$ pas-agent update --done 1 --next "Write tests"

3. Save a Checkpoint

Save a snapshot of your progress at meaningful milestones. This also records the git state and the files with uncommitted changes:

$ pas-agent checkpoint "Completed login endpoint and password hashing"
Checkpoint #1 saved: Completed login endpoint and password hashing
  Files with uncommitted changes: 4

4. Check Status

$ pas-agent status
Project:   my-project
...
Task:      Implement user authentication
Next:      Write tests

Completed (3):
   1. Created login endpoint
   2. Added password hashing
   3. Add token refresh

Remaining (1):
   1. Write tests

Git:       main @ abc1234d (uncommitted changes)

Checkpoints: 1

5. Export for Another Agent

Write the context into the file the next agent reads at startup:

$ pas-agent export --to codex
Created /home/me/my-project/AGENTS.md for codex.
codex reads AGENTS.md from the project root at session start.

If AGENTS.md already exists, PAS-Agent adds its own marked block and leaves the rest of the file untouched. Later exports replace only that block.

6. Continue in the Next Agent

Start the next agent in the same project. It loads the exported file at startup and sees your task, progress, and decisions.

Full Workflow

# Working in Claude Code
$ pas-agent init --task "Add user auth"
$ pas-agent update --completed "Login endpoint done" --next "Token refresh"
$ pas-agent checkpoint "Login complete"

# Switch to Codex
$ pas-agent export --to codex
$ codex  # reads AGENTS.md at startup

Next, see Workflows for when to start each agent and how to let your agent keep the session up to date for you.

PreviousInstallation NextWorkflows