pan-conversations git:20261101.b2e1603A

Immutable. This exact content never changes and is served at /api/v1/blob/24ac5b8c006d81ca.

---
name: pan-conversations
description: "pan conversations scan/search/list/show/current/cost/enrich/embed/move/link-pr/schedule — discover, index, search, reassign, link PRs to, and schedule prompts in Claude Code session history"
triggers:
  - pan conversations
  - pan conv
  - conversations scan
  - conversations search
  - conversations move
  - conv link-pr
  - conv schedule
allowed-tools:
  - Bash
  - Read
---

# Pan Conversations

`pan conversations` (alias `pan conv`) discovers, indexes, and searches Claude Code
session history recorded in the `discovered_sessions` index, and reads/writes the
live `conversations` table (the same store the dashboard uses).

## Commands

```bash
pan conversations scan [dirs...] [--watched] [--system] [--dry-run] [--max-parallel <n>]
pan conversations search [query] [--workspace <path>] [--model <name>] [--since <time>] [--after <time>] [--before <time>] [--min-cost <n>] [--max-cost <n>] [--min-messages <n>] [--managed] [--unmanaged] [--enriched] [--not-enriched] [--tag <value>] [--tool <name>] [--file <path>] [--issue <id>] [--similar <id>] [--semantic <query>] [--format <fmt>] [--limit <n>] [--offset <n>]
pan conversations list [--workspace <path>] [--model <name>] [--since <time>] [--managed] [--enriched] [--format <fmt>] [--limit <n>] [--offset <n>]
pan conversations show <id> [--json]
pan conversations jsonl <conv-id> [--json]
pan conversations move <query> <projectKey>
pan conversations pending <conv> [--json]
pan conversations link-pr <query> <url|#42|owner/repo#42> [--source agent|manual]
pan conversations unlink-pr <query> <url|#42|owner/repo#42>
pan conversations prs <query> [--json]
pan conversations auto-archive-on-merge [on|off]
pan conversations schedule add <conv> (--cron <expr> | --hourly | --daily <HH:MM> | --weekdays <HH:MM> | --weekly "<day> HH:MM") (--prompt <text> | --prompt-file <path>) [--tz <zone>] [--paused] [--json]
pan conversations schedule list [conv] [--json]
pan conversations schedule pause <id>
pan conversations schedule resume <id>
pan conversations schedule rm <id>
pan conversations current [--json]
pan conversations cost [--since <time>] [--workspace <path>] [--by <field>] [--json]
pan conversations embed [ids...] [--regenerate] [--status] [--provider <name>] [--model <name>] [--max-parallel <n>]
pan conversations enrich [ids...] [--tier <n>] [--deep] [--full] [--upgrade] [--with <model>] [--prompt <text>] [--limit <n>] [--workspace <path>] [--since <time>] [--ids <ids>] [--max-parallel <n>] [--yes]
```

`jsonl` aliases `transcript`; `current` aliases `whoami`.

## Notes

- **`scan`** indexes `~/.claude/projects/` (or configured watch directories with
  `--watched`) into `discovered_sessions`. Run it before `search`/`list`/`cost` return
  anything for sessions not yet seen. `--dry-run` previews without writing.
- **`search`** is the full-text + filterable query surface; `--semantic <query>`
  and `--similar <id>` need embeddings generated first via `embed`. `--format ids`
  is useful for piping session IDs into another command.
- **`list`** is `search` without the free-text query — structured filters only.
- **`show <id>`** resolves `<id>` as a **conversation** id first (the same
  `/conv/<N>` namespace the dashboard uses), falling back to the
  `discovered_sessions` scan-order index if no conversation matches.
- **`jsonl <conv-id>`** prints the on-disk transcript path for a conversation id,
  or reports `expired` (path derivable but file missing) / `unknown` (no
  `claude_session_id` recorded) — use `--json` to read the `status` field
  programmatically.
- **`move <query> <projectKey>`** (PAN-1577) reassigns a conversation's project
  via the `project_key` override, without touching its cwd, tmux session, or
  backing JSONL file. `<query>` resolves by exact conversation name first, then
  a fuzzy match against conversation titles — an ambiguous fuzzy match (more than
  one title contains the query) or no match at all exits non-zero listing the
  candidates. `<projectKey>` is the project's yaml key (from `projects.yaml`),
  not its display name. Requires the dashboard running (`pan up`) — the command
  PATCHes `/api/conversations/:name/move`.
- **`pending <conv>`** (PAN-4641) lists the messages queued with
  `pan tell --when-limit-resets` that have not been delivered yet, in queue
  order: `#<id>  <status>  <not before>  <text preview>`, plus the last error when
  one is set. `<conv>` takes the same forms as `pan tell` (`conv/2972`, a
  conversation name, a dashboard URL). `--json` prints the rows. Edit or cancel a
  queued message from the conversation timeline in the dashboard.
- **`link-pr` / `unlink-pr` / `prs`** (PAN-3822) link a pull request to a
  conversation so its row and header show the PR badge. `<query>` resolves like
  `move`; `pan conv current` names your own conversation. Only a repository
  configured for the conversation's project is accepted (`#42` = that repo).
  Inside an agent the source is `agent`. Branch detection links a PR on its
  own only for a conversation in a linked git worktree, or an agent
  conversation, never one in the primary checkout. Unlinking hides the PR from
  branch detection too. Works with the dashboard down (writes the link directly).
  `auto-archive-on-merge` (default off) archives an operator conversation once
  all its linked PRs are merged or closed; never agent conversations, never a
  live session.
- **`schedule`** (PAN-4640) runs a prompt in a conversation on a recurring
  schedule. `<conv>` accepts `self` (also `.`, `current`, `me`) for the
  conversation you are running in, a conversation number, a name, or a unique
  title match. Presets (`--hourly`, `--daily`, `--weekdays`, `--weekly "mon 09:00"`)
  compile to a 5-field cron; `--prompt-file` reads a long prompt from disk. The
  time zone defaults to this machine's zone, and runs must be at least 15
  minutes apart. The dashboard fires it, so it survives harness and dashboard
  restarts: a stopped session is resumed first, missed runs collapse into one,
  and a failed run is recorded, not retried. Agent conversations and vault
  copies cannot be scheduled. Writes work with the dashboard down.
- **`enrich`**/**`embed`** call out to an LLM/embedding provider and cost money;
  `enrich` prompts for confirmation unless `--yes` is passed. `--tier 3`
  (`--deep`) and `--full` are the expensive, most-thorough options.
- **`current`** is deterministic — it reads the current process's own recorded
  session identity, it does not scan or guess.