Documentation · v0.1.0

Every subcommand, every flag.

seshy is a single static Go binary with zero dependencies. It reads the history of seven coding agents, read-only, and resumes any session with the agent's own native command — the real thread, not a summary. Here is everything it does.

The interactive picker

Run seshy in any directory to open a fuzzy-searchable terminal UI of every session that ran there, newest first, color-coded by agent.

`seshy [path]`

With no arguments it uses the current directory. Pass a path to point it elsewhere. Inside the picker:

↑ / ↓ — move the selection
/ or just type — fuzzy-filter by prompt or agent
p — toggle the preview pane
h — hide/show headless & automated runs (persists to config)
↵ — resume the selected session
q — quit without resuming

seshy — ~/repos/control-panel

~/repos/control-panel · 23 sessions · 7 agents

filter › deploy

2m agoclaudestop the deploy. i lied in the PR description.

1h agocodexdeleted prod. it's fine. is it fine?

3h agodroidthere's a meeting about me now

↑↓ move/ filterp previewh headless↵ resumeq quit

list & summary

Non-interactive readouts. list is a table for humans (JSON when piped); summary is a compact digest tuned for agents.

`seshy list [path]`

A scannable table of sessions in a directory. When the output is piped, it switches to JSON automatically — no flag needed.

`seshy summary [path]`

A compact digest of a project's sessions, designed to be cheap for an agent to read and reason over.

seshy list — ~/repos/myapp

$ seshy list ~/repos/myapp

AGE AGENT PROMPT

2m ago claude fix the failing auth test

1h ago codex add a /health endpoint

4h ago grok refactor the config loader

# piped? same data, as JSON.

last

Skip the picker entirely. seshy last resumes the single most recent session in a directory.

`seshy last [path]`

The fastest way back into whatever you were just doing. seshy finds the newest session for the directory and execs that agent's native resume command immediately.

seshy last

$ seshy last

resuming claude · 2m ago · ~/repos/control-panel

exec: claude --resume 9f3a…c1

all — every repo on the machine

An interactive picker of the most recent sessions across every repo. It pages — loading a page at a time and pulling in more as you scroll — so it stays instant even with thousands of sessions.

`seshy all`

The header shows "showing N of M" so you always know how much is loaded. Repo names are fuzzy-filterable, so you can jump to any project from anywhere.

Most-recent-first across all repos
Pages in more results as you scroll
Fuzzy-filter by repo name

seshy all

showing 50 of 1,284 · all repos

filter › panel

2m agoclaudecontrol-panel · wire the alerts digest

1h agocodexcontrol-panel · add /health endpoint

3h agodroidcontrol-panel · fix the schedule worker

↑↓ move/ filterh headless↵ resumescroll to load more

sessions — the JSON index

Every session across all agents and repos as JSON: an uncapped index for tooling and pipelines. It returns path, agent, dir, mtime, id, and resume — without reading file contents, so it stays fast.

`seshy sessions`

Where list is scoped to a directory, sessions is the whole machine. Use it to feed dashboards, build your own picker, or index your history however you like.

seshy sessions

$ seshy sessions | jq '.[0]'

"agent": "claude",

"dir": "~/repos/control-panel",

"id": "9f3a…c1",

"mtime": "2026-06-07T11:58:02Z",

"path": "~/.claude/…/9f3a.jsonl",

"resume": "claude --resume 9f3a…c1"

search — across all your history

Content search across all agents. Each hit prints an excerpt and the native resume command. Global by default; pass a path to scope it.

`seshy search <pattern> [path]`

Find that conversation where you solved this exact thing before. Flags:

-i — case-insensitive match
--regex — treat the pattern as a regular expression
Pass a path to scope the search to one project

seshy search

$ seshy search "rate limit" -i

claude · ~/repos/api · 3d ago

…added a token-bucket RATE LIMIT on /login…

claude --resume 71b0…4e

codex · ~/repos/gw · 2w ago

…the rate limiter rejects bursts over 20/s…

codex resume a2d8…90

config — see or hide headless runs

seshy lists headless and automated runs (claude -p, codex exec) by default — sessions the native CLIs never show — so you can resume them too. Two optional toggles hide them when you want a cleaner list: live with h in the picker, or on the command line. Settings live in ~/.config/seshy/config.json (XDG-aware).

`seshy config` / `seshy config set <key> <true|false>`

By default they're listed and resumable like anything else. If they're crowding a busy history, toggle them off and they disappear everywhere seshy lists sessions.

hideClaudeHeadless — hides claude -p / Agent-SDK sessions
hideCodexExec — hides codex exec sessions
h in any picker toggles both live and saves the change here

seshy config

$ seshy config set hideClaudeHeadless true

ok · claude -p sessions now hidden

$ seshy config

hideClaudeHeadless true

hideCodexExec false

retention — who is deleting your history

Claude Code and Gemini CLI delete sessions older than 30 days by default; the other eight agents seshy knows keep everything. seshy retention reports every store's location, disk usage, and policy — and manages the two knobs that exist.

`seshy retention`

The table covers ten agents — the seven resumable ones plus Gemini CLI, Cursor CLI, and Copilot CLI. -o json / ndjson emit the same report for tooling.

`seshy retention set <agent> <days|off>`

claude — days or off; writes cleanupPeriodDays in ~/.claude/settings.json. seshy never writes 0 (old Claude versions treated it as “never save sessions”).
gemini — a duration (365d, 52w, 12m — m is months) or off; writes general.sessionRetention in ~/.gemini/settings.json.
Every write backs the file up to .bak, preserves unknown keys, and refuses malformed JSON.

`seshy retention protect`

Plans the changes that give every auto-deleting agent at least --days (default 365) of retention, shows exact before → after edits, and asks before writing. --yes skips the prompt (required when non-interactive).

seshy retention protect

$ seshy retention protect

claude ~/.claude/settings.json

cleanupPeriodDays 30d (default) → 365

gemini ~/.gemini/settings.json

sessionRetention.maxAge 30d → "365d"

each file is backed up to <file>.bak first

Apply 2 changes? [y/N] y

applied claude cleanupPeriodDays = 365

applied gemini sessionRetention.maxAge = "365d"

Agent Skills, included

seshy ships Agent Skills in the repo's .claude/skills/ — drop them into your skills directory and natural-language recall over your history becomes something your agent just does. seshy doesn't do semantic search — it's why your agent can.

seshy & conversation-search

Your agent can answer "find where we set up the rate limiter" or "resume the deploy session from this morning" — it expands your question into literal seshy search runs, judges the excerpts, and hands back the right thread with its resume command. Powered by the same binary; no model or vector store in seshy itself.

seshy — list, summarize, search, and resume sessions
conversation-search — topic search over session contents
If you've rolled your own history-search skill, this is that — in the box

agent — using the skill

user: find where we fixed the auth test

→ seshy search "auth test" -i

found 2 matches across claude, codex

resume: claude --resume 9f3a…c1

Commands reference

The full surface area at a glance.

Command	What it does
seshy [path]	Open the interactive picker for a directory (defaults to the current directory).
seshy list [path]	Print a table of sessions for a directory. Emits JSON when piped.
seshy summary [path]	Print a compact, agent-friendly digest of a project’s sessions.
seshy last [path]	Instantly resume the most recent session in a directory.
seshy all	Interactive picker of the most recent sessions across every repo. Pages as you scroll.
seshy sessions	Emit every session across all agents and repos as JSON (uncapped index).
seshy search <pattern> [path]	Content search across all agents. Prints an excerpt + resume command per hit.
seshy retention	Per-agent session stores, disk usage, and deletion policies — ten agents in one table (-o json for tooling).
seshy retention set <agent> <days\|off>	Change a deleting agent’s retention (claude, gemini). Backs the settings file up to .bak first.
seshy retention protect [--days N] [--yes]	Raise every auto-deleting agent to at least N days (default 365) in one confirmed step.
seshy config	Show current config values.
seshy config set <key> <true\|false>	Toggle a config key (hideClaudeHeadless, hideCodexExec).

Flags reference

Flag	Effect
-C, --cwd <dir>	Run as if invoked from <dir>.
--all	Include sessions from subdirectories, not just the exact path.
--agent <name>	Limit results to a single agent (claude, codex, grok, pi, opencode, agy, droid; retention also knows gemini, cursor, copilot).
-n, --num <int>	Max sessions per agent (default 10).
-o, --format <fmt>	Output format: table, json, or ndjson.
-i	search only — case-insensitive match.
--regex	search only — treat the pattern as a regular expression.

Install seshy.

A single static binary, zero dependencies.

Homebrew

macOS & Linux, kept up to date.

$ brew install buddyh/tap/seshy

Go

Build from source with the Go toolchain.

$ go install github.com/buddyh/seshy@latest