Architecture

PAS-Agent is a minimal, local-first tool: one small Rust binary and one JSON file per project. This page explains how the pieces fit together.

How It Works

1. One file holds the session. init creates.pas-agent/session.json at the root of your git repository (it asksgit rev-parse --show-toplevel where that is). Every other command walks up from the current directory until it finds that file, so they work from any subfolder.
2. Commands edit the file. update and remove load the session, change the task state, and save it again. Saving writes a temporary file and renames it over the old one, so a crash or a full disk can't leave a half-written session.
3. Checkpoints ask git what changed. checkpoint runsgit for the branch, the commit, and git status, then stores that next to a copy of the task state. PAS-Agent's own directory is excluded, so the session never shows up as "changed".
4. Export renders Markdown. export refreshes the git state and turns the session into Markdown. Every value is flattened to a single line and escaped, so nothing you type can break the document or fake its markers.
5. The block goes where the agent looks. The Markdown is wrapped inpas-agent:start / pas-agent:end markers and written into the file the target agent loads at startup. If the file has a block, only the block is replaced; if not, the block is appended. Your own content is never touched.
6. The next agent just reads a file. No plugin or API is involved. The agent loads its instruction file as usual and finds the task, progress, and decisions in it.

The session format carries a schema_version. New fields get defaults, so older files keep loading, and a file from a newer version is rejected rather than misread. PAS-Agent makes no network requests at any point.

System Overview

PAS-Agent CLI
    ↓ writes
.pas-agent/session.json  (portable state)
    ↓ generates
CLAUDE.md / AGENTS.md / GEMINI.md  (inside a marked block)
    ↓ read at startup by
Claude Code / Codex / OpenCode / Cursor / Kiro CLI / Antigravity / Gemini CLI

Crate Structure

crates/
├── pas-agent-core/     # Session model, storage, context generation
└── pas-agent-cli/      # CLI binary (clap-based)

pas-agent-core

Core library with no CLI dependencies. Handles:

• Session data model (Session, TaskState, Checkpoint, FileState, GitRef, Agent)
• File-based session storage (SessionStore)
• Context generation and non-destructive writing (generate_context, write_context_file)
• Git state capture (capture_git_state, get_changed_files)

pas-agent-cli

CLI binary providing user-facing commands: init,checkpoint, status, list,export, update, remove.

Storage Format

One versioned JSON file per project, written atomically. No database is required.

.pas-agent/
└── session.json   # task state, git state, checkpoints

Integration Model

PAS-Agent does not parse internal agent session formats. Instead, it generates instruction files that each agent reads at session start:

Design Decisions