csess-0.8.1 is not a library.

csess

Fast, reliable CLI that lists Claude Code sessions for a folder and its subfolder projects. Built for speed — designed to be called by Claude itself with --json.

Why

Claude stores each session as a *.jsonl file under ~/.claude/projects/<encoded-cwd>/. csess resolves those into a readable list (name, last-active, message count, path), correctly handling nested projects and folder names containing dashes.

Install

From crates.io

cargo install csess

From source (Cargo)

cargo install --git https://github.com/sibincbaby/csess

Prebuilt binary

Download the latest static binary from Releases, then:

tar xzf csess-*-linux-musl.tar.gz
sudo mv csess /usr/local/bin/

Install script

curl -fsSL https://raw.githubusercontent.com/sibincbaby/csess/main/install.sh | bash

Usage

csess                      # sessions for the current dir + subfolders
csess /home/me/projects    # a specific folder tree
csess --global             # every Claude project on the machine
csess -s auth              # fuzzy search name/path
csess --period today       # only today's sessions
csess --since 7d --sort messages
csess --json               # machine-readable output (for scripts / AI)

Options

Flag	Description
`PATH`	Folder to scan (default: cwd)
`-g, --global`	All Claude projects
`-R, --no-recursive`	Exact folder only
`-s, --search TERM`	Fuzzy match on name/path
`--since` / `--until`	`2026-06-01` \| `7d` \| `24h` \| `30m`
`--period`	`today` \| `yesterday` \| `week` \| `month`
`--sort`	`active` \| `created` \| `name` \| `messages` \| `size`
`-r, --reverse`	Reverse order
`-n, --limit N`	Cap results (with `--show`, tails the last N messages)
`--show ID_OR_NAME`	Print one session's full transcript
`--before UUID`	With `--show`: only messages older than this uuid (scroll-up cursor)
`--role user\|assistant`	Filter to one side (with `--show` or `--grep`)
`--grep TEXT`	Search message text; with `--show` filters that transcript, else scans across sessions
`--json`	JSON output

JSON fields

session_id, short, name, cwd, last_active (RFC3339), created, message_count, git_branch, version, size_bytes, file_path.

Transcripts & search

csess -g --show 09f8a9f7              # full conversation (human-readable)
csess -g --show 09f8a9f7 --json       # structured, for an agent/UI
csess -g --show 09f8a9f7 -n 20        # only the last 20 messages
csess -g --show 09f8a9f7 --role user  # just your prompts
csess -g --show 09f8a9f7 --grep error # messages in that session mentioning "error"
csess -g --grep "panic"               # search every session; prints matches + snippets
csess -g --grep "panic" --json        # { "schema_version": 1, "matches": [...] }

For AI agents (Claude Code)

Two steps — install the binary, then install the skill (a root SKILL.md does not auto-register; it must live under ~/.claude/skills/):

# 1. binary
cargo install --git https://github.com/sibincbaby/csess

# 2. skill → enables /csess in Claude Code
mkdir -p ~/.claude/skills/csess
curl -fsSL https://raw.githubusercontent.com/sibincbaby/csess/main/SKILL.md \
  -o ~/.claude/skills/csess/SKILL.md

See SKILL.md for when and how an agent should call csess (prefer --json).

csess 0.8.1