---
name: csess
description: Use when you need to find Claude Code sessions for a folder, or read a full session transcript by id — list names/times/sizes, or fetch the whole conversation as JSON. Fast; prefer --json for parsing.
---
# Looking up Claude sessions with `csess`
`csess` does two things: (1) **list** Claude Code sessions for a folder and its
subprojects, and (2) **show** one session's full conversation transcript.
## When to use
- "What sessions exist for this project?" → `csess --json`
- "Find my session about X" → `csess -s X --json`
- "Which session was most recently active?" → `csess --json -n 1`
- "Show / open / read the full conversation for session <id>" → `csess -g --show <id> --json`
- "Give me the last 20 messages of that session" → `csess -g --show <id> -n 20 --json`
- "Load older messages as the user scrolls up" → page with `--before <uuid>` (see Paging)
## Listing
Always prefer `--json` when you will parse the result.
```bash
csess --json # current dir + subfolders
csess /path/to/proj --json # a specific tree
csess --global --json # all projects (-g)
csess -s "auth" --json # fuzzy search on name + path
csess --sort size --json # sort: active(default)|created|name|messages|size; -r reverses
csess -n 10 --json # limit to N results
```
### List output (JSON array)
Each item: `session_id`, `short`, `name`, `cwd`, `last_active`, `created`,
`message_count`, `git_branch`, `version`, `size_bytes`, `file_path`.
Sorted newest-first by default. (Human table also shows a SIZE column.)
## Showing a full transcript
`--show <ID_OR_NAME>` prints one session's whole conversation. Match is by full
id, short id (first 8 chars), or a substring of the name. Use `-g` so it finds
the session regardless of which project folder it lives in. If the query matches
more than one session it lists the candidates and exits non-zero — narrow it.
```bash
csess -g --show 09f8a9f7 # human-readable transcript
csess -g --show 09f8a9f7 --json # structured, for an agent/UI
csess -g --show 09f8a9f7 -n 20 --json # only the last 20 messages (tail)
csess -g --show 09f8a9f7 --before <uuid> -n 20 --json # 20 messages older than <uuid>
```
Synthetic resume entries that Claude Code writes to its own log (the `isMeta`
"Continue from where you left off." / `<synthetic>` "No response requested."
pairs) are filtered out, so the transcript and `message_count` match what the
Claude UI shows — don't expect them in the output.
- **Human** (no `--json`): a header, then each message as `## role · timestamp`
with content flattened; tool activity shown as `[tool_use: NAME] {input}`,
`[tool_result] …`, `[thinking] …`.
- **JSON** (`--json`): for rendering a chat UI. Shape:
```jsonc
{
"session_id", "name", "cwd", "created", "git_branch", "version", "message_count",
"messages": [
{
"role": "user" | "assistant",
"timestamp": "RFC3339",
"uuid": "…", // stable key
"sidechain": true, // present only for subagent turns
"content": … // raw Anthropic content: a string, OR an array of blocks
}
]
}
```
`content` blocks are raw and untouched: `{type:"text",text}`,
`{type:"thinking",thinking}`, `{type:"tool_use",id,name,input}`,
`{type:"tool_result",tool_use_id,content,is_error}`. Pair a result to its call
via `tool_use_id` ↔ `tool_use.id`. `-n N` keeps the last N messages.
## Paging (scroll-up / lazy load)
For a chat UI that loads history on scroll, page backwards with a uuid cursor —
not an offset (offsets drift when the active session appends new turns):
```bash
csess -g --show <id> -n 50 --json # initial: newest 50; keep oldest uuid
csess -g --show <id> --before <oldest-uuid> -n 50 --json # scroll up: next 50 older; prepend
# stop when fewer than 50 come back (reached the top)
```
`--before <uuid>` drops that message and everything after it, then `-n` keeps the
last N of what remains. The `uuid` of each message is the stable cursor. `--before`
requires `--show`.
## Install
1. Binary: `cargo install --git https://github.com/sibincbaby/csess`
2. This skill: copy this file to `~/.claude/skills/csess/SKILL.md` so `/csess` is available.