<!-- GENERATED by scripts/build-docs.mjs from the live Commander tree (src/cli/program.ts). Do not edit by hand. -->

# pai session

> Session management: list, info, checkpoint, handover, cleanup, slug, tag, route.

Short forms: `pai pause`, `pai end`, `pai resume <name>`.

## Synopsis

```
pai session <subcommand> [options]
```

## Subcommands

| Command | Description |
|---------|-------------|
| [`pai session list`](#pai-session-list) | Resumable sessions catalog — named sessions with resume status. |
| [`pai session restore`](#pai-session-restore) | Restore transcripts PAI displaced into sessions/ so claude --resume can find them again. Reports what is unresumable, which checkpoints promise it, and which transcripts are empty. Dry run unless --execute is given. |
| [`pai session info <project-slug> <number>`](#pai-session-info-project-slug-number) | Show full details for a specific session |
| [`pai session rename <project-slug> <number> <new-slug>`](#pai-session-rename-project-slug-number-new-slug) | Rename a session note — updates file on disk, H1 title, and registry |
| [`pai session slug <project-slug> <number>`](#pai-session-slug-project-slug-number) | Generate a descriptive slug from the session JSONL transcript |
| [`pai session tag <project-slug> <number> [tags...]`](#pai-session-tag-project-slug-number-tags) | Set or show tags on a session. Tags can be space-separated or comma-separated. |
| [`pai session route <project-slug> <number> <target-project>`](#pai-session-route-project-slug-number-target-project) | Create a cross-reference link from a session to a target project |
| [`pai session handover [project-slug] [number-or-latest]`](#pai-session-handover-project-slug-number-or-latest) | Write a ## Continue section to the project's TODO.md. |
| [`pai session checkpoint <message>`](#pai-session-checkpoint-message) | Append a timestamped checkpoint to the active session note. |
| [`pai session autosave`](#pai-session-autosave) | Refresh the ## Continue checkpoint from the transcript and working tree. |
| [`pai session active`](#pai-session-active) | Show currently active Claude Code sessions. |
| [`pai session recent`](#pai-session-recent) | [Deprecated] Use `pai session list` or `pai sessions` instead. |
| [`pai session goto <name-or-id>`](#pai-session-goto-name-or-id) | Go to a session: resume if a resumable snapshot exists, start fresh otherwise. |
| [`pai session pause`](#pai-session-pause) | Write a ## Continue checkpoint to the project's TODO.md. |
| [`pai session auto-route`](#pai-session-auto-route) | Auto-detect which project this session belongs to. |
| [`pai session cleanup [project-slug]`](#pai-session-cleanup-project-slug) | Clean up session notes: delete empties, auto-name unnamed, move into YYYY/MM/ hierarchy, renumber |

### pai session list

Resumable sessions catalog — named sessions with resume status.

Short form: pai sessions
Default shows all sessions you've named or that are resumable.
Use --all to also show unnamed orphan sessions.

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `-n <count>` | Maximum sessions to show (default: 20) | `20` |
| `--all` | Include unnamed orphan sessions (not in clc registry) |  |
| `--json` | Output raw JSON instead of formatted table |  |


### pai session restore

Restore transcripts PAI displaced into sessions/ so claude --resume can find them again. Reports what is unresumable, which checkpoints promise it, and which transcripts are empty. Dry run unless --execute is given.

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--execute` | Actually restore (hardlink back to the project root) |  |
| `--promised` | Only sessions a checkpoint tells you to resume |  |
| `--cwd <path>` | Only sessions belonging to this working directory |  |
| `--all` | List every displaced session, not just the largest few |  |
| `--include-stubs` | Also restore transcripts that hold no conversation |  |
| `--json` | Output raw JSON instead of a formatted report |  |


### pai session info <project-slug> <number>

Show full details for a specific session

**Arguments**

| Argument | Kind |
|----------|------|
| `<project-slug>` | required |
| `<number>` | required |


### pai session rename <project-slug> <number> <new-slug>

Rename a session note — updates file on disk, H1 title, and registry

**Arguments**

| Argument | Kind |
|----------|------|
| `<project-slug>` | required |
| `<number>` | required |
| `<new-slug>` | required |


### pai session slug <project-slug> <number>

Generate a descriptive slug from the session JSONL transcript

**Arguments**

| Argument | Kind |
|----------|------|
| `<project-slug>` | required |
| `<number>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--apply` | Rename the session note using the generated slug |  |


### pai session tag <project-slug> <number> [tags...]

Set or show tags on a session. Tags can be space-separated or comma-separated.

**Arguments**

| Argument | Kind |
|----------|------|
| `<project-slug>` | required |
| `<number>` | required |
| `[tags...]` | variadic |


### pai session route <project-slug> <number> <target-project>

Create a cross-reference link from a session to a target project

**Arguments**

| Argument | Kind |
|----------|------|
| `<project-slug>` | required |
| `<number>` | required |
| `<target-project>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--type <type>` | Link type: related \| follow-up \| reference | `related` |


### pai session handover [project-slug] [number-or-latest]

Write a ## Continue section to the project's TODO.md.

Called automatically from session-stop and pre-compact hooks.
Records the last session identifier, timestamp, and working directory
so the next session can resume from the correct context.

**Arguments**

| Argument | Kind |
|----------|------|
| `[project-slug]` | optional |
| `[number-or-latest]` | optional |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--session-id <uuid>` | Claude session UUID. Used to decide whether an existing authored checkpoint belongs to this session and must be preserved. Without it the comparison falls back to the session note filename, which the stop hook itself renames — so pass it whenever it is known. |  |


### pai session checkpoint <message>

Append a timestamped checkpoint to the active session note.

Designed for hooks (PostToolUse, UserPromptSubmit) — fast and silent.
Rate-limited: skips silently if last checkpoint was < --min-gap seconds ago.

**Arguments**

| Argument | Kind |
|----------|------|
| `<message>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--min-gap <seconds>` | Minimum seconds between checkpoints (default: 300 = 5 minutes) | `300` |


### pai session autosave

Refresh the ## Continue checkpoint from the transcript and working tree.

Runs unattended from live hooks so an interrupted session still leaves
a usable handover. Writes in auto mode, so a model-authored checkpoint
for the same session is preserved untouched. Silent; always exits 0.

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--session-id <uuid>` | Claude session UUID — the key that decides whether an existing authored checkpoint belongs to this session and must be left alone. |  |
| `--min-gap <seconds>` | Minimum seconds between autosaves, shared across all triggers (default: 240) | `240` |
| `--dry-run` | Print the block that would be written and exit |  |


### pai session active

Show currently active Claude Code sessions.

Detects live sessions by checking which JSONL transcript files
were recently modified in ~/.claude/projects/.

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--minutes <n>` | Consider sessions active if modified within N minutes (default: 60) | `60` |
| `--json` | Output raw JSON instead of formatted display |  |


### pai session recent

[Deprecated] Use `pai session list` or `pai sessions` instead.

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `-n <count>` | Maximum sessions to show (default: 20) | `20` |
| `--all` | Include unnamed orphan sessions (not in clc registry) |  |
| `--json` | Output raw JSON instead of formatted table |  |


### pai session goto <name-or-id>

Go to a session: resume if a resumable snapshot exists, start fresh otherwise.

Recommended short form: pai resume <name>
Resolves by clc/registry name (case-insensitive) or UUID prefix.
Sends '/Name <name>\ngo' as the initial prompt so the PAI ## Continue hook fires.

**Arguments**

| Argument | Kind |
|----------|------|
| `<name-or-id>` | required |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--skip-name` | Do not prepend /Name to set the session name in chrome |  |
| `--skip-go` | Do not append \ngo to trigger PAI auto-resume (## Continue) |  |
| `--dry-run` | Print the exact argv and cwd, then exit without launching |  |


### pai session pause

Write a ## Continue checkpoint to the project's TODO.md.

Recommended short form: pai pause
Ctrl+C bypasses the stop-hook, orphaning the session (cannot --resume).
Use /exit inside Claude Code to preserve full session resumability.

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--dry-run` | Preview the ## Continue block without writing it |  |
| `--body-file <path>` | File holding the checkpoint markdown to persist ('-' reads stdin). Required unless --no-body. |  |
| `--session-id <uuid>` | Claude Code session UUID — recorded as the `claude --resume` handle |  |
| `--no-body` | Deliberately write a metadata-only checkpoint (no content) |  |


### pai session auto-route

Auto-detect which project this session belongs to.

Tries: (1) path match in registry, (2) Notes/PAI.md marker walk, (3) topic detection.
Designed for use in CLAUDE.md session-start hooks.

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--cwd <path>` | Working directory to detect from (default: process.cwd()) |  |
| `--context <text>` | Conversation context for topic-based fallback routing |  |
| `--json` | Output raw JSON instead of formatted display |  |


### pai session cleanup [project-slug]

Clean up session notes: delete empties, auto-name unnamed, move into YYYY/MM/ hierarchy, renumber

**Arguments**

| Argument | Kind |
|----------|------|
| `[project-slug]` | optional |

**Options**

| Option | Description | Default |
|--------|-------------|---------|
| `--execute` | Actually perform the cleanup (default is dry-run) |  |
| `--no-renumber` | Skip renumbering sessions after deletions |  |
| `--no-reindex` | Skip triggering memory re-index after moves |  |


## See also

[`pai audit`](audit.md) · [`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai config`](config.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai identity`](identity.md) · [`pai kg`](kg.md) · [`pai launch`](launch.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai worker`](worker.md) · [`pai zettel`](zettel.md)

Run `pai help <area>` to read any of these in the terminal.