opencode-manager 0.2.0 → 0.3.0

package/README.md

@@ -29,6 +29,31 @@ Terminal UI for inspecting, filtering, and pruning OpenCode metadata stored on d
 - Copy sessions to other projects (`P`) with new session ID generation.
 - Rich help overlay with live key hints (`?` or `H`).
 - Zero-install via `bunx` so even CI shells can run it without cloning.
+- **Token counting**: View token usage per session, per project, and globally.
+
+## Token Counting
+
+The TUI displays token telemetry from OpenCode's stored message data at three levels:
+
+1. **Per-session**: Shows a breakdown in the session Details pane (Input, Output, Reasoning, Cache Read, Cache Write, Total).
+2. **Per-project**: Shows total tokens for the highlighted project in the Projects panel.
+3. **Global**: Shows total tokens across all sessions in the header bar.
+
+### Token Definitions
+| Field | Description |
+|---|---|
+| **Input** | Tokens in the prompt sent to the model |
+| **Output** | Tokens generated by the model |
+| **Reasoning** | Tokens used for chain-of-thought reasoning (some models) |
+| **Cache Read** | Tokens read from provider cache |
+| **Cache Write** | Tokens written to provider cache |
+| **Total** | Sum of all token fields |
+
+### Behavior Notes
+- Token data is read from `storage/message/<sessionId>/*.json` files (assistant messages only).
+- If token telemetry is missing or unreadable, the display shows `?` instead of `0`.
+- Token summaries are cached in memory and refreshed when you press `R` to reload.
+- Large datasets are handled with lazy computation to avoid UI freezes.
 
 ## Requirements
 - [Bun](https://bun.sh) **1.1.0+** (developed/tested on 1.2.x).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-manager",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Terminal UI for inspecting OpenCode metadata stores.",
   "type": "module",
   "license": "MIT",

package/src/lib/opencode-data.ts

@@ -4,6 +4,29 @@ import { homedir } from "node:os"
 
 export type ProjectState = "present" | "missing" | "unknown"
 
+// ========================
+// Token Types
+// ========================
+
+export type TokenBreakdown = {
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+  total: number
+}
+
+export type TokenSummary =
+  | { kind: "known"; tokens: TokenBreakdown }
+  | { kind: "unknown"; reason: "missing" | "parse_error" | "no_messages" }
+
+export type AggregateTokenSummary = {
+  total: TokenSummary
+  knownOnly?: TokenBreakdown
+  unknownSessions?: number
+}
+
 export interface ProjectRecord {
   index: number
   bucket: ProjectBucket
@@ -186,11 +209,18 @@ export async function loadSessionRecords(options: SessionLoadOptions = {}): Prom
   const projectDirs = await fs.readdir(sessionRoot, { withFileTypes: true })
   const sessions: SessionRecord[] = []
 
+  // Some older OpenCode layouts may store message/part data under `storage/session/*`.
+  // Avoid treating those as project IDs when loading sessions.
+  const reservedSessionDirs = new Set(["message", "part"])
+
   for (const dirent of projectDirs) {
     if (!dirent.isDirectory()) {
       continue
     }
     const currentProjectId = dirent.name
+    if (reservedSessionDirs.has(currentProjectId)) {
+      continue
+    }
     if (options.projectId && options.projectId !== currentProjectId) {
       continue
     }
@@ -446,3 +476,259 @@ export async function moveSessions(
 
   return { succeeded, failed }
 }
+
+// ========================
+// Token Aggregation
+// ========================
+
+// Cache: key includes root+project+session+updatedAtMs to avoid collisions.
+const tokenCache = new Map<string, TokenSummary>()
+
+function getCacheKey(session: SessionRecord, root: string): string {
+  const updatedMs = session.updatedAt?.getTime() ?? session.createdAt?.getTime() ?? 0
+  return JSON.stringify([root, session.projectId, session.sessionId, updatedMs])
+}
+
+export function clearTokenCache(): void {
+  tokenCache.clear()
+}
+
+function emptyBreakdown(): TokenBreakdown {
+  return {
+    input: 0,
+    output: 0,
+    reasoning: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    total: 0,
+  }
+}
+
+function addBreakdown(a: TokenBreakdown, b: TokenBreakdown): TokenBreakdown {
+  return {
+    input: a.input + b.input,
+    output: a.output + b.output,
+    reasoning: a.reasoning + b.reasoning,
+    cacheRead: a.cacheRead + b.cacheRead,
+    cacheWrite: a.cacheWrite + b.cacheWrite,
+    total: a.total + b.total,
+  }
+}
+
+interface MessageTokens {
+  input?: number
+  output?: number
+  reasoning?: number
+  cache?: {
+    read?: number
+    write?: number
+  }
+}
+
+interface MessagePayload {
+  role?: string
+  tokens?: MessageTokens | null
+}
+
+function asTokenNumber(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return null
+  }
+  if (value < 0) {
+    return null
+  }
+  return value
+}
+
+function parseMessageTokens(tokens: MessageTokens | null | undefined): TokenBreakdown | null {
+  if (!tokens || typeof tokens !== "object") {
+    return null
+  }
+
+  const input = asTokenNumber(tokens.input)
+  const output = asTokenNumber(tokens.output)
+  const reasoning = asTokenNumber(tokens.reasoning)
+  const cacheRead = asTokenNumber(tokens.cache?.read)
+  const cacheWrite = asTokenNumber(tokens.cache?.write)
+
+  const hasAny = input !== null || output !== null || reasoning !== null || cacheRead !== null || cacheWrite !== null
+  if (!hasAny) {
+    return null
+  }
+
+  const breakdown = emptyBreakdown()
+  breakdown.input = input ?? 0
+  breakdown.output = output ?? 0
+  breakdown.reasoning = reasoning ?? 0
+  breakdown.cacheRead = cacheRead ?? 0
+  breakdown.cacheWrite = cacheWrite ?? 0
+  breakdown.total = breakdown.input + breakdown.output + breakdown.reasoning + breakdown.cacheRead + breakdown.cacheWrite
+  return breakdown
+}
+
+async function loadSessionMessagePaths(sessionId: string, root: string): Promise<string[] | null> {
+  // Primary path: storage/message/<sessionId>
+  const primaryPath = join(root, 'storage', 'message', sessionId)
+  if (await pathExists(primaryPath)) {
+    try {
+      const entries = await fs.readdir(primaryPath)
+      return entries
+        .filter((e) => e.endsWith('.json'))
+        .map((e) => join(primaryPath, e))
+    } catch {
+      return null
+    }
+  }
+
+  // Legacy fallback: storage/session/message/<sessionId>
+  const legacyPath = join(root, 'storage', 'session', 'message', sessionId)
+  if (await pathExists(legacyPath)) {
+    try {
+      const entries = await fs.readdir(legacyPath)
+      return entries
+        .filter((e) => e.endsWith('.json'))
+        .map((e) => join(legacyPath, e))
+    } catch {
+      return null
+    }
+  }
+
+  return null
+}
+
+export async function computeSessionTokenSummary(
+  session: SessionRecord,
+  root: string = DEFAULT_ROOT
+): Promise<TokenSummary> {
+  const normalizedRoot = resolve(root)
+  const cacheKey = getCacheKey(session, normalizedRoot)
+  const cached = tokenCache.get(cacheKey)
+  if (cached) {
+    return cached
+  }
+
+  const messagePaths = await loadSessionMessagePaths(session.sessionId, normalizedRoot)
+  if (messagePaths === null) {
+    const result: TokenSummary = { kind: 'unknown', reason: 'missing' }
+    tokenCache.set(cacheKey, result)
+    return result
+  }
+
+  if (messagePaths.length === 0) {
+    const result: TokenSummary = { kind: 'unknown', reason: 'no_messages' }
+    tokenCache.set(cacheKey, result)
+    return result
+  }
+
+  const breakdown = emptyBreakdown()
+  let foundAnyAssistant = false
+
+  for (const msgPath of messagePaths) {
+    const payload = await readJsonFile<MessagePayload>(msgPath)
+    if (!payload) {
+      const result: TokenSummary = { kind: "unknown", reason: "parse_error" }
+      tokenCache.set(cacheKey, result)
+      return result
+    }
+
+    // Only sum assistant messages (they have token telemetry)
+    if (payload.role !== "assistant") {
+      continue
+    }
+
+    foundAnyAssistant = true
+
+    const msgTokens = parseMessageTokens(payload.tokens)
+    if (!msgTokens) {
+      const result: TokenSummary = { kind: "unknown", reason: "missing" }
+      tokenCache.set(cacheKey, result)
+      return result
+    }
+
+    breakdown.input += msgTokens.input
+    breakdown.output += msgTokens.output
+    breakdown.reasoning += msgTokens.reasoning
+    breakdown.cacheRead += msgTokens.cacheRead
+    breakdown.cacheWrite += msgTokens.cacheWrite
+  }
+
+  if (!foundAnyAssistant) {
+    const result: TokenSummary = { kind: "unknown", reason: "no_messages" }
+    tokenCache.set(cacheKey, result)
+    return result
+  }
+
+  // Compute total
+  breakdown.total = breakdown.input + breakdown.output + breakdown.reasoning + breakdown.cacheRead + breakdown.cacheWrite
+
+  const result: TokenSummary = { kind: "known", tokens: breakdown }
+  tokenCache.set(cacheKey, result)
+  return result
+}
+
+export async function computeProjectTokenSummary(
+  projectId: string,
+  sessions: SessionRecord[],
+  root: string = DEFAULT_ROOT
+): Promise<AggregateTokenSummary> {
+  const projectSessions = sessions.filter((s) => s.projectId === projectId)
+  return computeAggregateTokenSummary(projectSessions, root)
+}
+
+export async function computeGlobalTokenSummary(
+  sessions: SessionRecord[],
+  root: string = DEFAULT_ROOT
+): Promise<AggregateTokenSummary> {
+  return computeAggregateTokenSummary(sessions, root)
+}
+
+async function computeAggregateTokenSummary(
+  sessions: SessionRecord[],
+  root: string
+): Promise<AggregateTokenSummary> {
+  if (sessions.length === 0) {
+    return {
+      total: { kind: 'unknown', reason: 'no_messages' },
+      knownOnly: emptyBreakdown(),
+      unknownSessions: 0,
+    }
+  }
+
+  const knownOnly = emptyBreakdown()
+  let unknownSessions = 0
+
+  const normalizedRoot = resolve(root)
+
+  for (const session of sessions) {
+    const summary = await computeSessionTokenSummary(session, normalizedRoot)
+    if (summary.kind === "known") {
+      knownOnly.input += summary.tokens.input
+      knownOnly.output += summary.tokens.output
+      knownOnly.reasoning += summary.tokens.reasoning
+      knownOnly.cacheRead += summary.tokens.cacheRead
+      knownOnly.cacheWrite += summary.tokens.cacheWrite
+      knownOnly.total += summary.tokens.total
+    } else {
+      unknownSessions += 1
+    }
+  }
+
+  // Recompute knownOnly.total (defensive)
+  knownOnly.total = knownOnly.input + knownOnly.output + knownOnly.reasoning + knownOnly.cacheRead + knownOnly.cacheWrite
+
+  // If all sessions are unknown, total is unknown
+  if (unknownSessions === sessions.length) {
+    return {
+      total: { kind: 'unknown', reason: 'missing' },
+      knownOnly: emptyBreakdown(),
+      unknownSessions,
+    }
+  }
+
+  // Otherwise, total is the known aggregate (even if some sessions are unknown)
+  return {
+    total: { kind: 'known', tokens: { ...knownOnly } },
+    knownOnly,
+    unknownSessions,
+  }
+}

package/src/opencode-tui.tsx

@@ -30,6 +30,13 @@ import {
   copySessions,
   moveSessions,
   BatchOperationResult,
+  TokenSummary,
+  TokenBreakdown,
+  AggregateTokenSummary,
+  computeSessionTokenSummary,
+  computeProjectTokenSummary,
+  computeGlobalTokenSummary,
+  clearTokenCache,
 } from "./lib/opencode-data"
 
 type TabKey = "projects" | "sessions"
@@ -64,6 +71,7 @@ type SessionsPanelProps = {
   locked: boolean
   projectFilter: string | null
   searchQuery: string
+  globalTokenSummary: AggregateTokenSummary | null
   onNotify: (message: string, level?: NotificationLevel) => void
   requestConfirm: (state: ConfirmState) => void
   onClearFilter: () => void
@@ -82,6 +90,46 @@ const PALETTE = {
   muted: "#9ca3af", // gray
 } as const
 
+// Token formatting helpers
+function formatTokenCount(n: number): string {
+  if (n >= 1_000_000) {
+    return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`
+  }
+  if (n >= 1_000) {
+    return `${(n / 1_000).toFixed(1).replace(/\.0$/, "")}k`
+  }
+  return String(n)
+}
+
+function formatTokenBreakdown(tokens: TokenBreakdown): string[] {
+  return [
+    `Input: ${formatTokenCount(tokens.input)}`,
+    `Output: ${formatTokenCount(tokens.output)}`,
+    `Reasoning: ${formatTokenCount(tokens.reasoning)}`,
+    `Cache Read: ${formatTokenCount(tokens.cacheRead)}`,
+    `Cache Write: ${formatTokenCount(tokens.cacheWrite)}`,
+    `Total: ${formatTokenCount(tokens.total)}`,
+  ]
+}
+
+function formatTokenSummaryShort(summary: TokenSummary): string {
+  if (summary.kind === 'unknown') {
+    return '?'
+  }
+  return formatTokenCount(summary.tokens.total)
+}
+
+function formatAggregateSummaryShort(summary: AggregateTokenSummary): string {
+  if (summary.total.kind === 'unknown') {
+    return '?'
+  }
+  const base = formatTokenCount(summary.total.tokens.total)
+  if (summary.unknownSessions && summary.unknownSessions > 0) {
+    return `${base} (+${summary.unknownSessions} unknown)`
+  }
+  return base
+}
+
 function copyToClipboard(text: string): void {
   const cmd = process.platform === "darwin" ? "pbcopy" : "xclip -selection clipboard"
   const proc = exec(cmd, (error) => {
@@ -210,6 +258,9 @@ const ProjectsPanel = forwardRef<PanelHandle, ProjectsPanelProps>(function Proje
   const [missingOnly, setMissingOnly] = useState(false)
   const [cursor, setCursor] = useState(0)
   const [selectedIndexes, setSelectedIndexes] = useState<Set<number>>(new Set())
+  // Token state for projects
+  const [allSessions, setAllSessions] = useState<SessionRecord[]>([])
+  const [currentProjectTokens, setCurrentProjectTokens] = useState<AggregateTokenSummary | null>(null)
 
   const missingCount = useMemo(() => records.filter((record) => record.state === "missing").length, [records])
 
@@ -280,6 +331,34 @@ const ProjectsPanel = forwardRef<PanelHandle, ProjectsPanelProps>(function Proje
     })
   }, [visibleRecords.length])
 
+  // Load all sessions once for token computation
+  useEffect(() => {
+    let cancelled = false
+    loadSessionRecords({ root }).then((sessions) => {
+      if (!cancelled) {
+        setAllSessions(sessions)
+      }
+    })
+    return () => { cancelled = true }
+  }, [root, records]) // Re-fetch when projects change (implies sessions may have changed)
+
+  // Compute token summary for current project
+  useEffect(() => {
+    setCurrentProjectTokens(null)
+    if (!currentRecord || allSessions.length === 0) {
+      return
+    }
+    let cancelled = false
+    computeProjectTokenSummary(currentRecord.projectId, allSessions, root).then((summary) => {
+      if (!cancelled) {
+        setCurrentProjectTokens(summary)
+      }
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [currentRecord, allSessions, root])
+
   const toggleSelection = useCallback((record: ProjectRecord | undefined) => {
     if (!record) {
       return
@@ -447,6 +526,19 @@ const ProjectsPanel = forwardRef<PanelHandle, ProjectsPanelProps>(function Proje
               <text>Created: {formatDate(currentRecord.createdAt)}</text>
               <text>Path:</text>
               <text>{formatDisplayPath(currentRecord.worktree, { fullPath: true })}</text>
+              <box style={{ marginTop: 1 }}>
+                <text fg={PALETTE.accent}>Tokens: </text>
+                {currentProjectTokens?.total.kind === 'known' ? (
+                  <>
+                    <text fg={PALETTE.success}>Total: {formatTokenCount(currentProjectTokens.total.tokens.total)}</text>
+                    {currentProjectTokens.unknownSessions && currentProjectTokens.unknownSessions > 0 ? (
+                      <text fg={PALETTE.muted}> (+{currentProjectTokens.unknownSessions} unknown sessions)</text>
+                    ) : null}
+                  </>
+                ) : (
+                  <text fg={PALETTE.muted}>{currentProjectTokens ? '?' : 'loading...'}</text>
+                )}
+              </box>
             </box>
           ) : null}
         </box>
@@ -456,7 +548,7 @@ const ProjectsPanel = forwardRef<PanelHandle, ProjectsPanelProps>(function Proje
 })
 
 const SessionsPanel = forwardRef<PanelHandle, SessionsPanelProps>(function SessionsPanel(
-  { root, active, locked, projectFilter, searchQuery, onNotify, requestConfirm, onClearFilter },
+  { root, active, locked, projectFilter, searchQuery, globalTokenSummary, onNotify, requestConfirm, onClearFilter },
   ref,
 ) {
   const [records, setRecords] = useState<SessionRecord[]>([])
@@ -471,6 +563,9 @@ const SessionsPanel = forwardRef<PanelHandle, SessionsPanelProps>(function Sessi
   const [operationMode, setOperationMode] = useState<'move' | 'copy' | null>(null)
   const [availableProjects, setAvailableProjects] = useState<ProjectRecord[]>([])
   const [projectCursor, setProjectCursor] = useState(0)
+  // Token state
+  const [currentTokenSummary, setCurrentTokenSummary] = useState<TokenSummary | null>(null)
+  const [filteredTokenSummary, setFilteredTokenSummary] = useState<AggregateTokenSummary | null>(null)
 
   const visibleRecords = useMemo(() => {
     const sorted = [...records].sort((a, b) => {
@@ -548,6 +643,46 @@ const SessionsPanel = forwardRef<PanelHandle, SessionsPanelProps>(function Sessi
     })
   }, [visibleRecords.length])
 
+  // Compute token summary for current session
+  useEffect(() => {
+    setCurrentTokenSummary(null)
+    if (!currentSession) {
+      return
+    }
+    let cancelled = false
+    computeSessionTokenSummary(currentSession, root).then((summary) => {
+      if (!cancelled) {
+        setCurrentTokenSummary(summary)
+      }
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [currentSession, root])
+
+  // Compute filtered token summary (deferred to avoid UI freeze)
+  useEffect(() => {
+    setFilteredTokenSummary(null)
+    if (records.length === 0) {
+      return
+    }
+
+    let cancelled = false
+
+    // Compute filtered (project-only) if filter is active.
+    if (projectFilter) {
+      computeProjectTokenSummary(projectFilter, records, root).then((summary) => {
+        if (!cancelled) {
+          setFilteredTokenSummary(summary)
+        }
+      })
+    }
+
+    return () => {
+      cancelled = true
+    }
+  }, [records, projectFilter, root])
+
   const toggleSelection = useCallback((session: SessionRecord | undefined) => {
     if (!session) {
       return
@@ -875,6 +1010,33 @@ const SessionsPanel = forwardRef<PanelHandle, SessionsPanelProps>(function Sessi
               <text>Updated: {formatDate(currentSession.updatedAt || currentSession.createdAt)}</text>
               <text>Directory:</text>
               <text>{formatDisplayPath(currentSession.directory, { fullPath: true })}</text>
+              <box style={{ marginTop: 1 }}>
+                <text fg={PALETTE.accent}>Tokens: </text>
+                {currentTokenSummary?.kind === 'known' ? (
+                  <>
+                    <text>In: {formatTokenCount(currentTokenSummary.tokens.input)} </text>
+                    <text>Out: {formatTokenCount(currentTokenSummary.tokens.output)} </text>
+                    <text>Reason: {formatTokenCount(currentTokenSummary.tokens.reasoning)} </text>
+                    <text>Cache R: {formatTokenCount(currentTokenSummary.tokens.cacheRead)} </text>
+                    <text>Cache W: {formatTokenCount(currentTokenSummary.tokens.cacheWrite)} </text>
+                    <text fg={PALETTE.success}>Total: {formatTokenCount(currentTokenSummary.tokens.total)}</text>
+                  </>
+                ) : (
+                  <text fg={PALETTE.muted}>{currentTokenSummary ? '?' : 'loading...'}</text>
+                )}
+              </box>
+              {projectFilter && filteredTokenSummary ? (
+                <box style={{ marginTop: 1 }}>
+                  <text fg={PALETTE.info}>Filtered ({projectFilter}): </text>
+                  <text>{formatAggregateSummaryShort(filteredTokenSummary)}</text>
+                </box>
+              ) : null}
+              {globalTokenSummary ? (
+                <box>
+                  <text fg={PALETTE.primary}>Global: </text>
+                  <text>{formatAggregateSummaryShort(globalTokenSummary)}</text>
+                </box>
+              ) : null}
               <text fg={PALETTE.muted} style={{ marginTop: 1 }}>Press Y to copy ID</text>
             </box>
           ) : null}
@@ -1061,6 +1223,23 @@ const App = ({ root }: { root: string }) => {
   const [confirmState, setConfirmState] = useState<ConfirmState | null>(null)
   const [showHelp, setShowHelp] = useState(true)
   const [confirmBusy, setConfirmBusy] = useState(false)
+  // Global token state
+  const [globalTokens, setGlobalTokens] = useState<AggregateTokenSummary | null>(null)
+  const [tokenRefreshKey, setTokenRefreshKey] = useState(0)
+
+  // Load global tokens
+  useEffect(() => {
+    let cancelled = false
+    loadSessionRecords({ root }).then((sessions) => {
+      if (cancelled) return
+      return computeGlobalTokenSummary(sessions, root)
+    }).then((summary) => {
+      if (!cancelled && summary) {
+        setGlobalTokens(summary)
+      }
+    })
+    return () => { cancelled = true }
+  }, [root, tokenRefreshKey])
 
   const notify = useCallback((message: string, level: NotificationLevel = "info") => {
     setStatus(message)
@@ -1185,6 +1364,9 @@ const App = ({ root }: { root: string }) => {
       }
 
       if (letter === "r") {
+        // Clear token cache on reload
+        clearTokenCache()
+        setTokenRefreshKey((k) => k + 1)
         if (activeTab === "projects") {
           projectsRef.current?.refresh()
         } else {
@@ -1219,7 +1401,21 @@ const App = ({ root }: { root: string }) => {
   return (
     <box style={{ flexDirection: "column", padding: 1, flexGrow: 1 }}>
       <box flexDirection="column" marginBottom={1}>
-        <text fg="#a5b4fc">OpenCode Metadata Manager</text>
+        <box style={{ flexDirection: "row", gap: 2 }}>
+          <text fg="#a5b4fc">OpenCode Metadata Manager</text>
+          <text fg={PALETTE.muted}>|</text>
+          <text fg={PALETTE.accent}>Global Tokens: </text>
+          {globalTokens?.total.kind === 'known' ? (
+            <>
+              <text fg={PALETTE.success}>{formatTokenCount(globalTokens.total.tokens.total)}</text>
+              {globalTokens.unknownSessions && globalTokens.unknownSessions > 0 ? (
+                <text fg={PALETTE.muted}> (+{globalTokens.unknownSessions} unknown)</text>
+              ) : null}
+            </>
+          ) : (
+            <text fg={PALETTE.muted}>{globalTokens ? '?' : 'loading...'}</text>
+          )}
+        </box>
         <text>Root: {root}</text>
         <text>
           Tabs: [1] Projects [2] Sessions | Active: {activeTab} | Global: Tab switch, / search, X clear, R reload, Q quit, ? help
@@ -1254,6 +1450,7 @@ const App = ({ root }: { root: string }) => {
             locked={Boolean(confirmState) || showHelp}
             projectFilter={sessionFilter}
             searchQuery={activeTab === "sessions" ? searchQuery : ""}
+            globalTokenSummary={globalTokens}
             onNotify={notify}
             requestConfirm={requestConfirm}
             onClearFilter={clearSessionFilter}
@@ -1292,11 +1489,32 @@ function printUsage(): void {
 Usage: bun run tui [-- --root /path/to/storage]
 
 Key bindings:
-  Tab / 1 / 2  Switch between projects and sessions
-  R             Reload the active view
-  Q             Quit the application
-  Projects view: Space select, A select all, M toggle missing filter, D delete, Enter jump to sessions
-  Sessions view: Space select, D delete, C clear project filter, Enter show details
+  Tab / 1 / 2     Switch between projects and sessions
+  /               Start search (active tab)
+  X               Clear search
+  ? / H           Toggle help
+  R               Reload (and refresh token cache)
+  Q               Quit the application
+
+Projects view:
+  Space           Toggle selection
+  A               Select all (visible)
+  M               Toggle missing-only filter
+  D               Delete selected (with confirmation)
+  Enter           Jump to Sessions for project
+  Esc             Clear selection
+
+Sessions view:
+  Space           Toggle selection
+  S               Toggle sort (updated/created)
+  Shift+R         Rename session
+  M               Move selected sessions to project
+  P               Copy selected sessions to project
+  Y               Copy session ID to clipboard
+  C               Clear project filter
+  D               Delete selected (with confirmation)
+  Enter           Show details
+  Esc             Clear selection
 `)
 }