Using Pagr

Sessions & projects

Two nouns carry the whole product. A project is a folder you registered. A session is one agent working in one project. Everything you can text is about starting, steering or stopping a session.

Projects#

A project is a directory on your Mac that you have registered with pagr project add. Registration is the only way a folder becomes reachable, and the mapping from id to path lives exclusively in ~/.pagr/projects.json.

What the control plane knows about a project:

the opaque id, proj_ followed by 32 hex characters;
the display name, up to 80 characters;
up to ten aliases you chose, for referring to it in a message;
a repository hint — the remote host, the repository name and the default branch — read straight out of .git/config without shelling out to git.

It never learns the path. Full details in projects and path containment.

Sessions#

A session is one run of one agent in one project. The cloud pre-allocates the session id so both halves share a single identifier from the first moment, which is what makes a follow-up unambiguous.

Each session carries the project, the provider, a status, a task summary, and timestamps.

$pagr sessionsSESSION                                AGENT   STATUS   PROJECT                                UPDATEDses_3f81a0c7d24b4e9a8051c6f3b7e2d094  claude  working  proj_1b7e05c93d6a4f2e8c04b7a91f3d2e56  2026-08-25T18:52:11.004Z

pagr sessions reads from the running daemon over the local Unix socket, so it exits 3 if the daemon is not running.

Session status#

Session statuses
Status	Meaning
`starting`	The command reached the Mac; the agent process is coming up.
`working`	A turn is in flight.
`waiting_for_user`	The agent asked you a question and is idle until it gets one.
`waiting_for_approval`	The agent wants to do something that needs permission.
`idle`	Alive, nothing in flight. A follow-up starts a new turn.
`completed`	The turn finished. Still resumable — a follow-up picks the session back up rather than starting a new one.
`failed`, `stopped`	Ended by an error, or by you interrupting it.
`offline`, `unknown`	The Mac is unreachable, or the provider reported something unrecognised.

Steering versus queueing#

When you send a follow-up, the bridge decides how to deliver it. The protocol has three modes and the cloud sends auto unless told otherwise:

Instruction delivery modes
Mode	Behaviour
`auto`	Steer if the adapter reports it can steer an active turn and a turn is actually active. Otherwise queue.
`steer`	Inject into the turn already in flight.
`queue`	Hold it and deliver when the agent goes idle.

Review workflows#

Saying “when claude finishes have codex review it” creates a durable workflow rather than a one-off message. Two shapes exist:

Workflow types
Type	What it does
`implement_then_review`	Waits for the implementer session to finish, then starts the reviewer on the same project — read-only where the provider supports it.
`review_fix_loop`	The reviewer finds issues, the implementer fixes them, for up to two cycles.

Both require an active subscription and both providers connected on that Mac. If you do not name a reviewer, Pagr uses your default reviewer preference; if you have not set one, it picks the agent that is not doing the implementing.

Cancelling a workflow stops it scheduling anything further. It does not interrupt an agent turn that is already running — say “stop checkout-api” for that.