git:20260731.59d4ece to git:20260810.6a0a091

---

name: sessions

description: "Search, browse, and read agent conversation transcripts across Claude, Codex, Gemini, and OpenCode. Use this skill to find previous sessions, recover context, or inspect what agents have done."

argument-hint: "[search query or session ID]"

allowed-tools: Bash(agents sessions*), Bash(agents cost*), Bash(agents logs*)

user-invocable: true

---

# Sessions Skill

Search and browse agent conversation transcripts. This skill teaches you how to use the `agents sessions` CLI effectively.

## Basic Usage

```bash

# Interactive picker: browse and search recent sessions

agents sessions

# List sessions from current project

agents sessions | head -20

# Search sessions by text

agents sessions "add auth middleware"

# Filter by project across all directories

agents sessions --project agents-cli --all

```

## Filters

| Filter | Example | Description |

|--------|---------|-------------|

| `--agent` | `--agent claude` | Filter by agent type |

| `--all` | `--all` | Include sessions from every directory |

| `--project` | `--project myapp` | Filter by project name |

| `--since` | `--since 2h` | Only sessions newer than this |

| `--until` | `--until 2026-01-01` | Only sessions older than this |

| `--limit` | `--limit 10` | Maximum sessions to return |

| `--sort` | `--sort cost` | Order by `cost`, `duration`, or `recent` (default) |

| `--active` | `--active` | Only currently running sessions |

| `--teams` | `--teams` | Include team-spawned sessions |

## Reading Sessions

```bash

# Render session as markdown

agents sessions --markdown <session-id>

# Output as JSON

agents sessions --json <session-id>

# Include only specific roles

agents sessions --markdown --include user,assistant <session-id>

# Show only first/last N turns

agents sessions --markdown --last 10 <session-id>

```

## Artifacts

```bash

# List all files written or edited during a session

agents sessions --artifacts <session-id>

# Read a specific artifact

agents sessions --artifact <filename> <session-id>

```

## Live Tailing

```bash

# Live-tail a session file (Claude and Codex only)

agents sessions tail <session-id>

# Press Ctrl+C to stop

# Or the unified viewer: resolves a session id OR a host-dispatch run (from

# `agents run --host`), and -f follows either (a session tail here is

# `sessions tail` under the hood)

```

## Cost & Duration

Every session is priced offline at scan time (`costUsd`) and its wall-clock

runtime is stored (`durationMs`). Both appear in `--json` output, and the list

can be sorted by either.

```bash

# The 10 most expensive sessions, anywhere

agents sessions --all --sort cost --limit 10

# Longest-running sessions in this project

agents sessions --sort duration

# Per-session cost in JSON

agents sessions --all --sort cost --json | jq '.[] | {shortId, agent, costUsd, durationMs}'

```

Use `agents cost` for a fleet-wide rollup (daily $ histogram, top sessions,

per-agent/project/day breakdown):

```bash

agents cost # daily histogram + top-10 + per-agent breakdown

agents cost --since 30d # last 30 days

agents cost --by project # group by project instead of agent

agents cost --by day --json # machine-readable daily rollup

```

`agents cost` answers "how much did this cost?"; `agents usage` answers "how

much quota / rate limit is left?" — different commands.

## Tips

- Use `--active` to find sessions running right now across terminals, teams, cloud, and headless agents

- Use `--teams` to see what team-spawned agents are doing

- Use `--since 1h` for recent activity

- Use `--sort cost` / `--sort duration` to find your priciest or longest sessions

- `agents cost` for spend rollups; `agents usage` for rate-limit status

- Combine filters: `agents sessions --project myapp --since 1d --agent claude`