Sessions

Commands for handing off, resuming, checkpointing, and analyzing gptme sessions.

Local peer conversations

Agents in separate gptme conversations can exchange attributed messages without sharing a parent/subagent relationship:

gptme chats peers
gptme chats send TARGET --peer --sender SOURCE "Review my current approach"
gptme chats send TARGET --peer --sender SOURCE --branch experiment "New evidence"

Inside an agent session, the chats tool exposes list_peers() and send_peer_message(conversation_id, message). The sender defaults to the current conversation. Discovery is advisory and reports whether a local runtime has an addressable gptme conversation; it does not grant access to another user or support injecting into unrelated external harnesses.

Messages use the existing durable prompt queue. Updated TUI and server receivers can wake while idle; busy receivers consume peer input at a safe step boundary. A TUI wake preserves the unsent draft. Paused/interrupted or autowake-disabled receivers leave input queued. Plain CLI idle wake is not provided by this path. Both sender and receiver must use a version with peer support for idle wake.

Server sessions using an ACP runtime defer automatic peer wakes and leave the input queued; they never answer that input through the in-process runtime. If a server saves peer input but cannot dispatch its response worker, clients receive an explicit error. The input remains in the transcript without being requeued or appended again: start a new step to respond to it. Automatic retry after a dispatch failure is not provided.

Peer messages carry a sender conversation, PID and correlation ID. These are local same-user attribution, not authenticated identity or human approval. A successful send means queued, not read or executed. Do not automatically reply to every peer message or create unbounded agent-to-agent ping-pong loops.

Command reference

gptme-status

Generate a portable operator handoff / session-status document.

Produces a compact briefing: recent commits, disk usage, and any extra sections contributed by installed StatusProvider plugins.

Extra status fields (task queues, service health, journal entries) are provided by installed packages that register a gptme.status_providers entry point — no workspace auto-detection, no cwd code loading.

Examples:

gptme-util status # stdout

gptme-util status –write # write to status.md

gptme-util status -o /tmp/handoff.md # write to custom path

gptme-util status –no-markdown # plain-text output

gptme-util status –format table # compact Markdown table

gptme-util status –json # structured JSON

Usage

gptme-status [OPTIONS]

Options

--write

Write status document to status.md in repo root.

-o, --output <FILE>

Output file path (implies –write).

--markdown, --no-markdown

Output as Markdown (default: enabled). Use –no-markdown for plain text.

--format <output_format>

Output format: narrative (default) or table.

Options:

narrative | table

--json

Output status as JSON.

gptme-resume

Rehydrate a <<RESUMED SESSION>> prompt from a prior session trajectory.

Prints the resume prompt to stdout so it can be passed to gptme:

gptme – “$(gptme-resume)”

gptme-resume –last 1 –output json

Usage

gptme-resume [OPTIONS]

Options

--list

List recent sessions and exit.

--last <last>

Nth-from-last session to resume (0 = most recent).

Default:

0

--session <DIR>

Explicit path to a session directory.

--max-chars <max_chars>

Maximum prompt characters; must fit the session’s framing lines.

Default:

3000

--output <output_fmt>

Output format: ‘prompt’ (default) or ‘json’ metadata.

Default:

'prompt'

Options:

prompt | json

gptme-checkpoint

Lightweight session-level recovery markers for Git workspaces.

Records the current HEAD so an agent run that touches more than expected can be rewound with gptme-checkpoint restore. Not a replacement for git — see gptme-checkpoint create --help.

Usage

gptme-checkpoint [OPTIONS] COMMAND [ARGS]...

create

Record a checkpoint at the current HEAD.

Usage

gptme-checkpoint create [OPTIONS] [PATH]

Options

--include-dirty

Allow checkpointing a dirty git workspace (records HEAD only).

--session-id <session_id>

Custom session identifier.

Arguments

PATH

Optional argument

diff

Diff current state against a checkpoint.

Usage

gptme-checkpoint diff [OPTIONS] IDENTIFIER [PATH]

Arguments

IDENTIFIER

Required argument

PATH

Optional argument

list

List recorded checkpoints for the workspace.

Usage

gptme-checkpoint list [OPTIONS] [PATH]

Arguments

PATH

Optional argument

restore

Restore working tree to a checkpoint HEAD via git reset --hard.

Usage

gptme-checkpoint restore [OPTIONS] IDENTIFIER [PATH]

Options

--include-dirty

Allow restore in a dirty workspace (DISCARDS uncommitted changes).

Arguments

IDENTIFIER

Required argument

PATH

Optional argument

gptme-stats

Show global LLM usage and cost statistics across all conversation logs.

Cache-read tokens are included in the input-token count, not added on top.

See also: gptme-sessions cost (gptme-contrib) for cross-backend analytics (Claude Code, OpenRouter, Bedrock, etc.) and gptme-usage for pricing tables.

Usage

gptme-stats [OPTIONS]

Options

-d, --days <days>

Filter statistics to conversations modified in the last N days.

--include-test

Include test/eval conversations in statistics.

--json

Output statistics as JSON.