opencode-sesh 0.3.0 → 0.4.0

package/AGENTS.md

@@ -37,10 +37,14 @@ HOME=/tmp/fakehome bash install.sh   # installer smoke test (never touches ~/.co
 - `bin/` — flat; no subdirs. Scripts resolve siblings from their own location.
   Never hardcode install paths. `sesh-waiting.sh` owns the needs-input query
   (shared heuristic with the TUI sidebar copy, marked `NEEDS_INPUT_SQL` in
-  both); `sesh-prune.sh` archives stale sessions. Reads go through
-  `sqlite3 -readonly` (or `opencode db`); the single archive `UPDATE` in
-  `sesh-prune.sh` is the only sanctioned direct write (no archive endpoint
-  exists — deletes stay on `opencode session delete`).
+  both); `sesh-prune.sh` archives stale sessions; `sesh-costs.sh` sums
+  assistant-message cost per directory; `sesh-retitle.sh` renames placeholder
+  titles. Reads go through `sqlite3 -readonly` (or `opencode db`); the direct
+  `UPDATE`s in `sesh-prune.sh` (archive) and `sesh-retitle.sh` (title) are the
+  only sanctioned writes — neither has a CLI or API endpoint, and hard deletes
+  stay on `opencode session delete`.
+- `contrib/` — caller-side integrations (currently cmux). Nothing here may add
+  window management to sesh itself.
 - `tui/sesh-panel.tsx` — SolidJS panel, `/** @jsxImportSource @opentui/solid */`.
 - `opencode/tools/sesh-list.ts` — the agent-facing `sesh-list` tool.
 - `scripts/changelog.sh` — release tooling: drafts `[Unreleased]` from

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-24
+
+### Added
+
+- `sesh costs [--days N] [--json]` sums assistant-message cost per project, with
+  a recent window beside the lifetime total, so a day's work reads as a
+  per-project record.
+- `sesh retitle [--dry-run] [--yes]` replaces auto-generated placeholder titles
+  (`New session - …`) with the start of the session's first user message. Only
+  placeholder titles are touched.
+- `contrib/cmux/` documents driving sesh from cmux: command-palette entries,
+  shortcuts, resuming a session in its own workspace, and a global "resume from
+  anywhere" hotkey. The glue is caller-side; sesh stays terminal-agnostic.
+
+### Changed
+
+- Search now weights results: a title match outranks a transcript-only match and
+  the current project rises while a query is active. Pins still win outright,
+  and the idle list keeps pure pin+recency ordering.
 ## [0.3.0] - 2026-09-24
 
 ### Added
@@ -239,7 +258,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixture-database regression suite, TypeScript typechecking, and ShellCheck in
   CI.
 
-[Unreleased]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.7...v0.2.0

package/README.md

@@ -137,6 +137,18 @@ sessions are never touched; archiving is reversible, while `--delete`
 hard-deletes through `opencode session delete`. Without `--dry-run`, a TTY run
 confirms first and a non-TTY run needs `--yes`.
 
+`sesh costs [--days N] [--json]` sums assistant-message cost per project, with a
+recent window beside the lifetime total, so a day's work reads as a
+per-project record.
+
+`sesh retitle [--dry-run] [--yes]` replaces auto-generated placeholder titles
+(`New session - …`) with the start of the session's first user message. Only
+placeholder titles are touched, and the same dry-run/`--yes` gating applies.
+
+When searching, title matches outrank transcript-only matches and the current
+project rises, so the list answers "where was that thing I worked on" before it
+answers "what is newest". Pins still win outright.
+
 Because `--print` just emits the id and directory, `sesh` doubles as a scriptable
 session lookup:
 
@@ -195,6 +207,13 @@ All variables are optional.
 | `SESH_CACHE_DIR` | `~/.cache/sesh` | persistent search-index cache |
 | `SESH_PINS_FILE` | `${XDG_DATA_HOME:-~/.local/share}/sesh/pins.json` | shared persistent session/directory pins |
 
+## Integrations
+
+sesh is terminal-agnostic on purpose: it has no window-management code. The
+[`contrib/cmux/`](contrib/cmux/README.md) directory shows how to drive it from
+cmux — command-palette entries, shortcuts, resuming a session in its own
+workspace, and a global "resume from anywhere" hotkey — all caller-side.
+
 ## How it works
 
 `bin/sesh-list.sh` is the only `bin/` script that reads the opencode session

package/ROADMAP.md

@@ -0,0 +1,61 @@
+# Roadmap
+
+Productivity bets for sesh, roughly ordered by payoff. Status is tracked here
+as items land.
+
+## 1. Needs-input triage (done)
+
+**Problem:** with 100+ sessions, the bottleneck is not finding a session but
+knowing which ones are *waiting on you* (unanswered agent questions, stale
+runs awaiting approval) versus done versus dead. Today that means polling rows
+by hand.
+
+**Approach:** server-independent detection straight from the opencode SQLite
+store, so it works for every session, not just ones owned by the current TUI
+server (whose in-memory permission/question state is invisible cross-project):
+
+- a `question` tool part that is not `completed` with no later user message in
+  the same session → awaiting an answer;
+- a `tool` part stuck in `running` older than ~10 minutes → awaiting approval
+  or orphaned by a dead server.
+
+**Surfaces:** a "Needs input" section pinned above the directory groups in the
+TUI sidebar, plus a terminal listing (`sesh --needs-input`).
+
+## 2. Stale-session pruning (done)
+
+**Problem:** the list grows without bound (127+ rows), which slows scanning
+and bloats the transcript search index with archaeology.
+
+**Approach:** `sesh prune --older-than 30d` archives (never deletes) sessions
+older than the threshold: never pinned ones, never ones flagged as needing
+input. Archive is reversible; `--delete` stays the explicit hard-delete path
+through the existing two-step confirm. Interactive runs confirm with a
+candidate summary; non-TTY runs require `--yes`; `--dry-run` lists only.
+
+## 3. sesh ↔ cmux bridge (done)
+
+**Approach:** kept caller-side. sesh has no window-management code (a hard
+repo rule), so [`contrib/cmux/`](contrib/cmux/README.md) ships the cmux
+actions, shortcuts and a `--print --json` recipe that resumes a session in its
+own workspace. cmux calls sesh; sesh never calls cmux.
+
+## 4. Per-project cost digest (done)
+
+`sesh costs [--days N] [--json]` sums assistant-message cost per directory with
+a recent window beside the lifetime total, so a day's work reads as a
+per-project record. Message-level summing (not `session.cost`) keeps a
+half-finished day from dragging in a session's earlier history.
+
+## 5. Resume from anywhere (done)
+
+Covered by the same contrib recipes: `sesh --print --json` resolves a session
+non-interactively, so a cmux action, skhd binding or launcher can resume a
+specific session — or open the picker — from any context.
+
+## Smaller items (done)
+
+- Search weighting: title matches outrank transcript-only matches and the
+  current project rises while a query is active; pins still win outright.
+- `sesh retitle [--dry-run] [--yes]` replaces placeholder titles
+  (`New session - …`) with the start of the first user message.

package/bin/sesh

@@ -26,5 +26,13 @@ case ${1:-} in
     shift
     exec bash "$SCRIPT_DIR/sesh-prune.sh" "$@"
     ;;
+  costs)
+    shift
+    exec bash "$SCRIPT_DIR/sesh-costs.sh" "$@"
+    ;;
+  retitle)
+    shift
+    exec bash "$SCRIPT_DIR/sesh-retitle.sh" "$@"
+    ;;
 esac
 exec "$SCRIPT_DIR/sesh.sh" "$@"

package/bin/sesh-costs.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Per-directory cost digest: what each project spent in a recent window and
+# over its lifetime, so a day's work reads as a per-project record.
+#
+# Cost is summed from assistant-message `cost` (not `session.cost`) so a
+# partially-completed day does not drag a session's whole history into the
+# window — the same reason the TUI statusline differs from `session.cost`.
+#
+# Usage: sesh-costs.sh [--days N] [--json]
+#   --days N   window in days (default 1); 0 means lifetime only
+#   --json     machine-readable rows
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OPENCODE_BIN=${SESH_OPENCODE:-opencode}
+days=1
+emit_json=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --days) days=${2:-}; shift ;;
+    --days=*) days=${1#--days=} ;;
+    --json) emit_json=1 ;;
+    --help) echo "usage: ${0##*/} [--days N] [--json]"; exit 0 ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+case "$days" in ''|*[!0-9]*) echo "--days must be a non-negative integer" >&2; exit 2;; esac
+
+resolve_db() {
+  if [ -n "${SESH_DB:-}" ]; then printf '%s\n' "$SESH_DB"; return 0; fi
+  local from_cli=''
+  if command -v "$OPENCODE_BIN" >/dev/null 2>&1; then
+    from_cli=$("$OPENCODE_BIN" db path 2>/dev/null || true)
+  fi
+  if [ -n "$from_cli" ] && [ -f "$from_cli" ]; then printf '%s\n' "$from_cli"; return 0; fi
+  if [ -f "$HOME/.local/share/opencode/opencode.db" ]; then printf '%s\n' "$HOME/.local/share/opencode/opencode.db"; return 0; fi
+  return 1
+}
+
+SQLITE_BIN=''
+if [ -n "${SESH_SQLITE:-}" ]; then
+  SQLITE_BIN=$SESH_SQLITE
+elif command -v sqlite3 >/dev/null 2>&1; then
+  SQLITE_BIN=sqlite3
+fi
+
+DB_PATH=$(resolve_db) || { echo 'sesh: session database unavailable' >&2; exit 1; }
+[ -f "$DB_PATH" ] || { echo 'sesh: session database unavailable' >&2; exit 1; }
+
+NOW_MS=$(python3 -c 'import time; print(int(time.time() * 1000))' 2>/dev/null || echo "$(( $(date +%s) * 1000 ))")
+CUTOFF=$((NOW_MS - days * 86400000))
+
+# One pass over assistant messages; the window filter is a cheap CASE so the
+# lifetime total and the window total come back together.
+ROWS_QUERY="
+SELECT s.directory AS directory,
+  ROUND(SUM(CASE WHEN m.time_created >= $CUTOFF THEN COALESCE(json_extract(m.data, '\$.cost'), 0) ELSE 0 END), 4) AS window_cost,
+  ROUND(SUM(COALESCE(json_extract(m.data, '\$.cost'), 0)), 4) AS lifetime_cost,
+  COUNT(DISTINCT s.id) AS sessions,
+  SUM(CASE WHEN m.time_created >= $CUTOFF THEN COALESCE(json_extract(m.data, '\$.tokens.input'), 0) + COALESCE(json_extract(m.data, '\$.tokens.output'), 0) ELSE 0 END) AS window_tokens
+FROM message m
+JOIN session s ON s.id = m.session_id
+WHERE json_extract(m.data, '\$.role') = 'assistant'
+  AND json_extract(m.data, '\$.cost') IS NOT NULL
+GROUP BY s.directory
+ORDER BY lifetime_cost DESC;"
+
+if [ -n "$SQLITE_BIN" ]; then
+  ROWS=$("$SQLITE_BIN" -json -readonly "$DB_PATH" "$ROWS_QUERY")
+else
+  command -v "$OPENCODE_BIN" >/dev/null 2>&1 || { echo 'sesh: neither sqlite3 nor opencode is available' >&2; exit 1; }
+  ROWS=$("$OPENCODE_BIN" db "$ROWS_QUERY" --format json)
+fi
+[ -n "$ROWS" ] || ROWS='[]'
+
+if [ "$emit_json" = 1 ]; then
+  printf '%s\n' "$ROWS"
+  exit 0
+fi
+
+JQ_BIN=${SESH_JQ:-$(command -v jq || true)}
+[ -n "$JQ_BIN" ] || { echo 'sesh: jq is required for the table view (or use --json)' >&2; exit 1; }
+
+HOME_DIR=${HOME:-}
+printf '%s' "$ROWS" | "$JQ_BIN" -r --arg home "$HOME_DIR" --argjson days "$days" '
+  def pretty: if . == null or . == "" then "other"
+    elif ($home != "" and startswith($home + "/")) then "~" + .[$home | length:]
+    else . end;
+  def money:
+    if . == 0 then "—"
+    else ((.*100 | round | tostring) as $c
+      | "$" + (if ($c | length) == 1 then "0.0" + $c
+               elif ($c | length) == 2 then "0." + $c
+               else $c[0:-2] + "." + $c[-2:] end))
+    end;
+  (map(select(.lifetime_cost > 0)) | sort_by(-.lifetime_cost)) as $rows
+  | if ($rows | length) == 0 then "No assistant cost recorded."
+    else
+      (["WINDOW" + (if $days == 0 then "" else "(\($days)d)" end), "LIFETIME", "SESS", "DIRECTORY"] | @tsv),
+      ($rows[] | [((.window_cost) | money), ((.lifetime_cost) | money), (.sessions | tostring), (.directory | pretty)] | @tsv)
+    end
+' | column -t -s $'\t'

package/bin/sesh-list.sh

@@ -157,7 +157,7 @@ render() {
   {
     [ -n "$notice" ] && printf '\t\tunknown\t%s%s%s\t\tnotice:action\n' "$YELLOW" "$notice" "$RESET"
     [ -n "$state" ] && [ "$state" != fresh ] && printf '\t\tunknown\t%s%s%s\t\tnotice:live-state\n' "$YELLOW" "$state" "$RESET"
-    "$JQ_BIN" -sr --argjson pins "$("${BASH_SOURCE[0]%/*}/sesh-pins.sh" read)" --arg green "$GREEN" --arg cyan "$CYAN" --arg gray "$GRAY" --arg magenta "$MAGENTA" --arg red "$RED" --arg bold "$BOLD" --arg yellow "$YELLOW" --arg reset "$RESET" --arg query "$QUERY" --arg home "$HOME" --arg selected "$SELECTED_ID" '
+    "$JQ_BIN" -sr --argjson pins "$("${BASH_SOURCE[0]%/*}/sesh-pins.sh" read)" --arg green "$GREEN" --arg cyan "$CYAN" --arg gray "$GRAY" --arg magenta "$MAGENTA" --arg red "$RED" --arg bold "$BOLD" --arg yellow "$YELLOW" --arg reset "$RESET" --arg query "$QUERY" --arg home "$HOME" --arg cwd "$PWD" --arg selected "$SELECTED_ID" '
       def ago($epoch):
         ((now - ($epoch | tonumber)) | floor) as $s
         | if $s < 60 then "now" elif $s < 3600 then "\($s / 60 | floor)m" elif $s < 86400 then "\($s / 3600 | floor)h" else "\($s / 86400 | floor)d" end;
@@ -181,11 +181,19 @@ render() {
          else empty end),
         ($matched
        | group_by(.cwd)
+       # Search relevance, not just recency: a title hit outranks a
+       # transcript-only hit, and the current project rises while a query is
+       # active. Both are query-gated so the idle list keeps pure pin+recency
+       # ordering (the scope toggle, not this, is what narrows the list).
        | map({cwd: .[0].cwd, updated: (map(.updatedEpoch) | max),
               pinDirectory: (.[0].cwd as $dir | $pins.directories | index($dir) != null),
               pinSession: (any(.[]; .sessionId as $id | $pins.sessions | index($id) != null)),
-              items: (sort_by([(.sessionId as $id | $pins.sessions | index($id) != null), .updatedEpoch]) | reverse)})
-       | sort_by([.pinDirectory, .pinSession, .updated]) | reverse
+              current: (($q != "") and (.[0].cwd == $cwd)),
+              titleHit: (($q != "") and any(.[]; (.title | ascii_downcase | contains($q)))),
+              items: (sort_by([(.sessionId as $id | $pins.sessions | index($id) != null),
+                               (if $q != "" then (.title | ascii_downcase | contains($q)) else false end),
+                               .updatedEpoch]) | reverse)})
+       | sort_by([.pinDirectory, .pinSession, .current, .titleHit, .updated]) | reverse
        | .[] as $g
        | (["", "", "unknown", ($magenta + (if $g.pinDirectory then "★ " else "" end) + ($g.cwd | homepath | gsub("[\u0000-\u001f\u007f-\u009f]";" ")) + $reset), $g.cwd, ("hdr:" + $g.cwd)] | @tsv),
         ($g.items | to_entries[] | .key as $i | .value as $s

package/bin/sesh-retitle.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# Give auto-generated session titles a readable first line.
+#
+# opencode titles most sessions itself; a few keep their placeholder
+# ("New session - <ISO>") because they ended before a title was derived. This
+# replaces just those placeholders with the start of the session's first user
+# message, so the row scans like the rest of the list.
+#
+# It only ever touches titles matching the placeholder pattern, and the value
+# it overwrites carries no information (a timestamp), so nothing recoverable is
+# lost. The write is a single direct UPDATE through the same sqlite3-or-
+# `opencode db` path as `sesh prune` — opencode exposes no title endpoint in
+# the CLI, so a direct write is the only route.
+#
+# Usage: sesh-retitle.sh [--dry-run] [--yes] [--max-words N]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OPENCODE_BIN=${SESH_OPENCODE:-opencode}
+dry_run=0
+assume_yes=0
+max_words=8
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --dry-run) dry_run=1 ;;
+    --yes|-y) assume_yes=1 ;;
+    --max-words) max_words=${2:-}; shift ;;
+    --max-words=*) max_words=${1#--max-words=} ;;
+    --help) echo "usage: ${0##*/} [--dry-run] [--yes] [--max-words N]"; exit 0 ;;
+    *) echo "unknown option: $1" >&2; exit 2 ;;
+  esac
+  shift
+done
+case "$max_words" in ''|*[!0-9]*) echo "--max-words must be a positive integer" >&2; exit 2;; esac
+[ "$max_words" -gt 0 ] || { echo "--max-words must be positive" >&2; exit 2; }
+
+resolve_db() {
+  if [ -n "${SESH_DB:-}" ]; then printf '%s\n' "$SESH_DB"; return 0; fi
+  local from_cli=''
+  if command -v "$OPENCODE_BIN" >/dev/null 2>&1; then
+    from_cli=$("$OPENCODE_BIN" db path 2>/dev/null || true)
+  fi
+  if [ -n "$from_cli" ] && [ -f "$from_cli" ]; then printf '%s\n' "$from_cli"; return 0; fi
+  if [ -f "$HOME/.local/share/opencode/opencode.db" ]; then printf '%s\n' "$HOME/.local/share/opencode/opencode.db"; return 0; fi
+  return 1
+}
+
+SQLITE_BIN=''
+if [ -n "${SESH_SQLITE:-}" ]; then
+  SQLITE_BIN=$SESH_SQLITE
+elif command -v sqlite3 >/dev/null 2>&1; then
+  SQLITE_BIN=sqlite3
+fi
+
+DB_PATH=$(resolve_db) || { echo 'sesh: session database unavailable' >&2; exit 1; }
+[ -f "$DB_PATH" ] || { echo 'sesh: session database unavailable' >&2; exit 1; }
+
+if [ -n "$SQLITE_BIN" ]; then
+  query() { "$SQLITE_BIN" -json -readonly "$DB_PATH" "$1"; }
+  write_db() { "$SQLITE_BIN" "$DB_PATH" "$1"; }
+else
+  command -v "$OPENCODE_BIN" >/dev/null 2>&1 || { echo 'sesh: neither sqlite3 nor opencode is available' >&2; exit 1; }
+  query() { "$OPENCODE_BIN" db "$1" --format json; }
+  write_db() { "$OPENCODE_BIN" db "$1" --format json > /dev/null; }
+fi
+
+JQ_BIN=${SESH_JQ:-$(command -v jq || true)}
+[ -n "$JQ_BIN" ] || { echo 'sesh: jq is required' >&2; exit 1; }
+
+# The first user text part per placeholder-titled session, cleaned into a
+# candidate: image chips and markdown noise dropped, whitespace collapsed,
+# first `max_words` words kept.
+CANDIDATES=$(query "
+SELECT s.id AS id, s.directory AS directory, s.title AS old_title,
+  (SELECT p.data FROM part p
+     JOIN message m ON m.id = p.message_id
+     WHERE p.session_id = s.id
+       AND json_extract(p.data, '\$.type') = 'text'
+       AND json_extract(m.data, '\$.role') = 'user'
+     ORDER BY p.time_created ASC LIMIT 1) AS first_part
+FROM session s
+WHERE s.title LIKE 'New session - %'
+   OR TRIM(COALESCE(s.title, '')) = ''
+ORDER BY s.time_updated DESC;")
+[ -n "$CANDIDATES" ] || CANDIDATES='[]'
+
+PLAN=$(printf '%s' "$CANDIDATES" | "$JQ_BIN" -c --argjson words "$max_words" '
+  def derive:
+    (.first_part // "")
+    | (try (fromjson | .text) catch "")
+    | gsub("\\[Image #[0-9]+\\]"; " ")
+    | gsub("[#*_`>]"; " ")
+    | gsub("\\s+"; " ")
+    | sub("^ +"; "") | sub(" +$"; "")
+    | (split(" ") | map(select(. != "")))
+    | (if length == 0 then "" else .[0:$words] | join(" ") end)
+    | if length > 60 then .[0:57] + "..." else . end;
+  [ .[] | .new_title = derive | select(.new_title != "") ]')
+COUNT=$(printf '%s' "$PLAN" | "$JQ_BIN" -r 'length')
+
+if [ "$COUNT" = 0 ]; then
+  echo "No placeholder-titled sessions with a usable first message."
+  exit 0
+fi
+
+printf '%s' "$PLAN" | "$JQ_BIN" -r '
+  .[] | "\(.id)\t\(.new_title)\t\(.old_title)"' | while IFS=$'\t' read -r id new old; do
+  printf '%s\n  \033[90m%s\033[0m\n  → %s\n' "$id" "$old" "$new"
+done
+
+if [ "$dry_run" = 1 ]; then
+  printf 'Retitle %s session(s) (--dry-run: nothing changed).\n' "$COUNT" >&2
+  exit 0
+fi
+
+if [ "$assume_yes" = 0 ]; then
+  if [ -t 0 ]; then
+    printf 'Retitle %s session(s)? [y/N] ' "$COUNT"
+    reply=''
+    IFS= read -r -n 1 reply || reply=''
+    printf '\n'
+    case "$reply" in
+      y|Y) ;;
+      *) echo 'Cancelled; nothing was changed.'; exit 0 ;;
+    esac
+  else
+    echo "Refusing to retitle $COUNT session(s): pass --yes when stdin is not a terminal." >&2
+    exit 2
+  fi
+fi
+
+# Escape single quotes for the SQL string literal; ids are validated by shape.
+sql_escape() { printf '%s' "$1" | sed "s/'/''/g"; }
+printf '%s' "$PLAN" | "$JQ_BIN" -r '.[] | [.id, .new_title] | @tsv' | while IFS=$'\t' read -r id new; do
+  case "$id" in
+    ses_[A-Za-z0-9]*) ;;
+    *) echo "Refusing: unexpected session id shape." >&2; exit 1 ;;
+  esac
+  write_db "UPDATE session SET title = '$(sql_escape "$new")' WHERE id = '$id' AND (title LIKE 'New session - %' OR TRIM(COALESCE(title, '')) = '');"
+done
+echo "Retitled $COUNT session(s)."

package/contrib/cmux/README.md

@@ -0,0 +1,59 @@
+# sesh ↔ cmux
+
+Optional glue for running sesh inside [cmux](https://cmux.dev). Nothing here is
+bundled into the picker: sesh has no window-management code, and these recipes
+keep it that way. cmux calls sesh; sesh never calls cmux.
+
+## Command palette + shortcuts
+
+Merge [`cmux.json.snippet`](cmux.json.snippet) into `~/.config/cmux/cmux.json`
+(or `.cmux/cmux.json` in a project), then `cmux reload-config` (Cmd+Shift+,).
+You get:
+
+| Action | Shortcut | What it does |
+| --- | --- | --- |
+| `sesh.picker` | Cmd+Shift+S | Open the picker in a new tab |
+| `sesh.needs` | Cmd+Shift+I | List sessions waiting on you |
+| `sesh.costs` | — | Per-project spend digest |
+
+Paste only the actions you want; the `ui.newWorkspace` block is optional.
+
+## Resume a session in its own cmux workspace
+
+The picker resumes in place (it `cd`s and `exec`s opencode). To instead open a
+session in a **new cmux workspace** at its directory, shell out to cmux after
+resolving the session with sesh's scriptable lookup:
+
+```bash
+sesh --print --json --query "auth refactor" \
+  | jq -r '[.sessionId, .cwd] | @tsv' \
+  | while IFS=$'\t' read -r id cwd; do
+      cmux new-workspace --cwd "$cwd" --command "opencode --session $id"
+    done
+```
+
+Wrap that in a cmux `command` action (as above) or a shell function; it is
+caller-side on purpose, so sesh stays terminal-agnostic.
+
+## Needs-input triage from cmux
+
+`sesh --needs-input` prints (or `--json` emits) the sessions with unanswered
+agent questions or runs stuck mid-tool. Bind it to a shortcut and it becomes
+the "what is blocked on me right now" view without opening the picker.
+
+## Global hotkey (resume from anywhere)
+
+sesh is a normal CLI, so any system-wide launcher works — a cmux `shortcut`, an
+`skhd` binding, a Raycast/Hammerspoon script:
+
+```bash
+# skhd example: Cmd+Shift+S opens the picker in a new cmux workspace
+cmd + shift - s : cmux new-workspace --command "sesh"
+```
+
+Because `--print --json` resolves a session non-interactively, the same hook can
+resume a specific session without any UI:
+
+```bash
+cmd + alt - r : cmux new-workspace --command "opencode --session $(sesh --print --json --limit 1 | jq -r .sessionId)"
+```

package/contrib/cmux/cmux.json.snippet

@@ -0,0 +1,38 @@
+{
+  "actions": {
+    "sesh.picker": {
+      "type": "command",
+      "title": "sesh — session picker",
+      "subtitle": "Fuzzy-find and resume any opencode session",
+      "command": "sesh",
+      "target": "newTabInCurrentPane",
+      "palette": true,
+      "shortcut": "cmd+shift+s"
+    },
+    "sesh.needs": {
+      "type": "command",
+      "title": "sesh — needs input",
+      "subtitle": "Sessions waiting on you (questions, stuck runs)",
+      "command": "sesh --needs-input",
+      "target": "newTabInCurrentPane",
+      "palette": true,
+      "shortcut": "cmd+shift+i"
+    },
+    "sesh.costs": {
+      "type": "command",
+      "title": "sesh — cost digest",
+      "subtitle": "Spend per project, today and lifetime",
+      "command": "sesh costs",
+      "target": "newTabInCurrentPane",
+      "palette": true
+    }
+  },
+  "ui": {
+    "newWorkspace": {
+      "contextMenu": [
+        { "action": "sesh.picker", "title": "Resume a session" },
+        { "type": "separator" }
+      ]
+    }
+  }
+}

package/install.sh

@@ -235,9 +235,11 @@ for path in \
   bin/sesh.sh \
   bin/sesh-list.sh \
   bin/sesh-preview.sh \
+  bin/sesh-costs.sh \
   bin/sesh-delete.sh \
   bin/sesh-prune.sh \
   bin/sesh-refresh-worker.sh \
+  bin/sesh-retitle.sh \
   bin/sesh-waiting.sh \
   bin/sesh-shortcuts.sh \
   opencode/tools/sesh-list.ts \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-sesh",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Browse, search, preview and resume opencode sessions from the terminal and the TUI.",
   "license": "MIT",
@@ -26,12 +26,14 @@
   },
   "files": [
     "bin/",
+    "contrib/",
     "opencode/",
     "themes/",
     "tui/",
     "install.sh",
     "AGENTS.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "ROADMAP.md"
   ],
   "publishConfig": {
     "access": "public"