Reference · v1.21.0

Every flag, tool, and skill.

Nothing on this page is retyped. The help text below is what the binary prints, the 8MCP tools are the ones the server registers, and the 6 skills are the frontmatter of the files that ship. The build fails if any of that stops being true.

CLI

Verbatim from sessions --help, read out of src/cli.ts when this page was built.

sessions — find and resume AI coding sessions

Browse sessions from Claude Code, Codex, Pi, and OpenCode with fuzzy search.
Scoped to the current git repo.

Usage

  sessions                    Browse all sessions with fzf
  sessions <query>            Search session content for a phrase
  sessions --here             Scope to current repo only

Options

  --here           Scope to current git repo (default: all projects)
  --tool <name>    Filter: claude, codex, pi, opencode
  --errored        Only sessions that hit an error
  --file <path>    Only sessions that touched or read this path (substring
                   match; repeatable — every path must match). Newest first
                   when no query is given
  --mcp            Start as an MCP server (stdio transport)
  --clear-cache    Remove the search index (rebuilds on next use)
  -v, --version    Print the CLI version
  -h, --help       Show this help

Commands

  context          Print a context primer for the current repo (markdown)
                   --full widens detail; --limit/--days/--tool filter; --worktree
                   narrows to the current worktree; --out <path> writes to a file
  digest <session> Print the arc of one session as compact markdown (~8k chars):
                   each genuine user turn with its exchange's final assistant
                   reply. Accepts a JSONL file path or an indexed session id
  report           Generate a usage report (HTML dashboard, opens in browser)
                   --out <path> saves instead of opening; --format json|html|both
                   (default html); --stdout prints JSON; --here scopes to the
                   current project; --from/--to/--days/--month limit the period
  wrapped          Your year with AI agents, Spotify-Wrapped style (opens in
                   browser). --year <YYYY> wraps a past year; --out/--stdout,
                   --tool, --extras <json> add agent-authored slides
  memory mine      Mine past sessions for durable facts worth remembering and
                   print the candidate batch as JSON. --repo <path> scopes to one
                   repo container (default: the current repo); --all mines every
                   repo in the index; --since-last mines only transcripts changed
                   since the previous mine
  memory pending   Count the candidates awaiting triage and preview a few of
                   them, as JSON. Reads the store only; it never mines
  memory approve   Record a triage decision for one candidate, by id from the
  memory reject    mine's batch. Rejected candidates stop being emitted; snoozed
  memory snooze    ones stay hidden until their date passes AND new distinct
                   phrasings appear — no mine can produce that bump yet, so a
                   snooze currently hides a candidate indefinitely.
                   approve takes --always-on (return this memory for every topic,
                   and first) and --scope group:<name> (assign a project group
                   from ~/.local/share/sessions/groups.json)
  memory export    Write approved memories as a portable bundle on stdout (--out
                   <path> writes a file instead). Carries no local paths and no
                   triage state; there is no transport, the file is the seam
  memory import    Merge another author's bundle in as candidates to triage.
                   Never overwrites your own approve/reject decisions
  setup            Install plugin and configure MCP for detected tools
                   --hooks opts in to SessionStart auto-injection (off by
                   default); without it, an interactive prompt asks when on a TTY
  uninstall        Remove plugin, MCP config, and the SessionStart hook
  cleanup          Uninstall plugin + clear search index (full reset)

Search

  With no argument, opens fzf with session summaries.
  With an argument, greps across session content for matching
  sessions, then opens fzf with the results.

MCP tools · 8

All read-only. Start the server with sessions --mcp over stdio, or let sessions setup write the config for every agent CLI it finds.

Tool	Title	What it is for
search_sessions	Search past AI coding sessions	Ranked search across every session, message-granular. Returns the matching messages, not just the sessions — and a ready-to-run resume command. Top-k, so it is fast and not exhaustive.
grep_sessions	Grep every past session message	Every message matching a literal string or regex, with a true total. This is the one for "how many times did I say that" — ranked search would quietly miss some.
get_session_digest	Digest one session end to end	One session's whole arc in a single bounded call, around 2k tokens: every real turn you took, paired with the reply that closed it. Long sessions elide the middle, never the ends.
get_session_messages	Read messages from one session	The exact exchange a search matched — pass the hit index straight through as the offset. Ask for tool calls too and you see what the agent actually did, which the prose usually leaves out.
get_context_primer	Prime context for this repo	Where you left off here: recent sessions in detail, older ones as headlines, the branch you were on, and the last thing each one said.
get_memory	Standing instructions for this repo	The standing instructions you have already given — build conventions, tooling constraints, rules you should not have to restate. Scoped to this repo, its project group, and your cross-repo workflow rules.
get_activity_digest	Digest activity over a date range	A date range grouped by day and project. This is what a weekly summary or a standup is built from.
get_session_metrics	Usage metrics over a date range	Tool and project breakdown, daily activity, and the hours you are actually working.

Manual config

{
  "mcpServers": {
    "sessions": { "command": "sessions", "args": ["--mcp"] }
  }
}

Skills · 6

Trigger phrases are quoted straight out of each skill's own description — the text an agent matches your phrasing against. Works with Claude Code, Cursor, Codex, and anything else that reads the skills.sh format.

/contextoptional repo path
Prior decisions, dead ends, and the thread you left open.
“what was I doing here”“catch me up on this repo”“context primer”“what's the open thread”
/recallproject name or path
The reasoning behind one past decision, without paging a transcript.
“what did I do on [project]”“recall [topic]”“history of [project]”“when did I last work on [thing]”
/standup
Yesterday and today as terse bullets you can paste into Slack.
“standup”“what did I do yesterday”“daily summary”“what have I been working on”
/weekly-summary
A structured week, then a nudge toward any new memory worth keeping.
“weekly summary”“what did I do this week”“summarize my week”“weekly recap”
/session-metricstime period (e.g., "past week", "may", "past month")
Which tool you actually use, and the hours you actually work.
“how much have I been coding”“session stats”“show me metrics”“tool usage”
/memoryrepo path (optional, defaults to current repo)
A mined batch clustered and triaged — approve, reject, or snooze each one.
“triage memory”“review memory”“mine memory”“/memory”

Report flags

Everything after `sessions report`.

--format json\|html\|both\|text	What to emit. Default html. text prints to stdout and writes no file.
--out <path>	Save instead of opening in the browser.
--here	Restrict to the current project.
--from / --to YYYY-MM-DD	Inclusive local-date range. Default: all time.
--days N	Last N days.
--today / --this-week / --this-month / --last-month / --this-year	Presets that resolve to a date range.
--month YYYY-MM	A specific calendar month.
--tool claude\|codex\|pi\|opencode	Restrict to one tool. Default: all four.
--tz <IANA>	Timezone for day/hour bucketing.
--stdout	Print JSON to stdout and skip the JSON file.
--offline	Skip the pricing refresh; use cached or embedded pricing.
--refresh-pricing	Force a pricing refresh even if the cache is fresh.
--no-cache	Bypass the incremental parse cache and re-read every transcript.

Wrapped flags

Everything after `sessions wrapped`.

--year <YYYY>	Wrap a past calendar year. Default: this year.
--roast	Let an agent CLI improvise extra roast slides. Opt-in, fails open.
--roast-with <tool>	Choose the CLI. Default order: claude, then codex, then pi.
--extras <path>	Inject up to six slides of your own from a JSON array.
--stdout	Print the underlying JSON instead of opening the page.
--out <path>	Write the HTML somewhere instead of opening it.
--tool claude\|codex\|pi\|opencode	Restrict to one tool.

Memory

The triage lifecycle, as subcommands.

memory mine	Mine past sessions for durable facts. --repo scopes, --all mines everything, --since-last only what changed.
memory pending	Count and preview the untriaged backlog. Reads the store only; never mines.
memory approve <id>	Keep a candidate. --always-on exempts it from topic filtering; --scope group:<name> or repo:<path> binds it.
memory reject <id>	Dismiss a candidate. It stops being emitted.
memory snooze <id>	Hide a candidate without rejecting it.
memory merge <id> <id>…	Fold paraphrases into the first id.
memory export	Write approved memories as a portable bundle. No local paths leave the machine.
memory import <path>	Merge another author’s bundle in as candidates. Never lands as approved.