Sessions

A session is the core abstraction in PAS-Agent. It represents an active coding task with all its operational context.

Session Data Model

Project name: the project this session belongs to
Task description: what you're working on
Objective: the specific goal
Completed work: what's been done
Remaining work: what's left to do
Next action: the immediate next step
Blockers: current obstacles
Decisions: choices made during the session
Constraints: limitations or requirements
Discoveries: things learned during the session
Git state: branch, commit, and whether there are uncommitted changes
Checkpoints: saved snapshots of progress

Storage

Everything lives in a single JSON file at the project root:

.pas-agent/
├── session.json   # task state, git state, and all checkpoints
└── session.lock   # empty; locked while a command changes the session

Writes are atomic: the file is written to a temporary file and then renamed into place, so a crash can't leave a half-written session behind.

Commands that change the session (init, update,remove, checkpoint, export) take an operating-system lock on session.lock while they read, modify, and save, so several agents working in the same project never overwrite each other's changes. Slow work such as reading git or prompting for a checkpoint message happens outside the lock. Commands wait up to 5 seconds for it; PAS_AGENT_LOCK_TIMEOUT_MS changes that. status andlist only read and don't take it. The lock belongs to the running process, so a crash releases it automatically; the empty session.lock file that stays behind is harmless and is listed in .pas-agent/.gitignore.

File Format

session.json carries a schema_version. Missing fields are filled with defaults, so older files keep loading as fields are added. A file written by a newer PAS-Agent with a higher schema version is rejected with a clear error instead of being misread.

{
  "schema_version": 1,
  "id": "46d89609-104d-4a43-907d-dbca99704a85",
  "project_name": "my-project",
  "created_at": "2026-09-17T04:30:00Z",
  "updated_at": "2026-09-17T04:39:00Z",
  "task": {
    "description": "Implement user authentication",
    "objective": "",
    "completed": ["Created login endpoint"],
    "remaining": ["Add token refresh"],
    "next_action": "Implement token refresh endpoint",
    "blockers": [],
    "decisions": ["Use bcrypt for hashing"],
    "constraints": [],
    "discoveries": []
  },
  "git": { "branch": "main", "commit": "abc1234d…", "dirty": true },
  "checkpoints": [ … ]
}

Session Lifecycle

# Create
pas-agent init --task "..."

# Update
pas-agent update --completed "..." --remaining "..."
pas-agent update --done 1
pas-agent remove decisions 2

# Checkpoint
pas-agent checkpoint "..."

# Export (writes context for another agent)
pas-agent export --to codex

One Session Per Project

Each project holds one active session, at the git repository root, or in the directory where you ran init outside git. Commands run from a subdirectory walk up to find it.

Commit It or Keep It Local?

It's your choice. Commit .pas-agent/ to carry the session across machines or share it with teammates. Add it to .gitignore to keep it private. PAS-Agent ignores its own directory when it checks for uncommitted changes.

PreviousWorkflows NextCheckpoints