Sessions

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

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 piped into gptme:

gptme-resume | gptme -c “$(cat)”

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 context characters in the resume prompt.

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.