commands/session/ — Session Management Commands

Contents

Architecture

flowchart TD
  SESSION["/session command"] -->|"load()"| STSX["session.tsx"]
  STSX -->|"useAppState()"| RURL["remoteSessionUrl"]
  STSX -->|"qrToString()"| QR["QR Code Display"]
  STSX -->|"useKeybinding(ESC)"| DONE["onDone()"]

  RESUME["/resume command"] -->|"loadAllProjectsMessageLogs()"| LOGS["Session JSONL Files"]
  RESUME -->|"loadFullLog()"| FULL["Full Transcript"]
  RESUME -->|"restoreSessionMetadata()"| RESTORE["Session Restore"]

  EXPORT["/export command"] -->|"renderMessagesToPlainText()"| TXT["Plaintext File"]

  BRANCH["/branch command"] -->|"createFork()"| FORK["Forked JSONL"]
  FORK -->|"forkedFrom metadata"| LINEAGE["Fork Lineage"]

  LOGS -->|"~/.claude/sessions/"| DISK["Filesystem"]
  LOGS -->|".index/ lite logs"| LITE["Lite Log Index"]

Session Lifecycle

sequenceDiagram
  participant U as User
  participant B as Bootstrap
  participant S as SessionStorage
  participant A as AppState

  U->>B: claude --remote
  B->>A: Set remoteSessionUrl
  B->>S: Create session JSONL
  Note over S: ~/.claude/sessions/{projectHash}/{id}.jsonl

  U->>U: /session
  A-->>U: Display QR + URL

  U->>U: /resume
  S-->>U: List sessions (lite logs)
  U->>S: Select session
  S->>S: loadFullLog() if lite
  S->>A: restoreSessionMetadata()

  U->>U: /export
  S-->>U: renderMessagesToPlainText()

  U->>U: /branch
  S->>S: createFork() with new UUID
  Note over S: Copies messages up to branch point

Key Classes & Functions

Data Structures

Interactions

Configuration

Directory Map

session/
├── index.ts              ← Command registration (type: 'local-jsx', aliases: ['remote'])
└── session.tsx            ← SessionInfo component: QR code + URL display (~140 lines)

Related commands (separate directories):
├── resume/               ← /resume: session listing, search, and restore
├── export/               ← /export: plaintext transcript export
└── branch/               ← /branch: fork conversation with lineage tracking

Deep-Dive Highlights

Core mechanisms from the session ecosystem have been extracted into dedicated focus areas for in-depth exploration.

Code Examples

Example 1: Command Registration (Conditional Visibility)

// index.ts — Session command with conditional enablement
import type { Command } from '../../commands.js'
import { getIsRemoteMode } from '../../bootstrap/state.js'

const session = {
  type: 'local-jsx',
  name: 'session',
  aliases: ['remote'],
  description: 'Show remote session URL and QR code',
  isEnabled: () => getIsRemoteMode(),
  isHidden: !getIsRemoteMode(),
  load: () => import('./session.js'),
} satisfies Command

export default session

Example 2: SessionInfo Component with QR Generation

// session.tsx — SessionInfo component (simplified)
import React, { useState, useEffect } from 'react'
import { Box, Text } from 'ink'
import { useAppState } from '../../state/AppState.js'
import { useKeybinding } from '../../hooks/useKeybinding.js'
import { qrToString } from 'qrcode'
import { Pane } from '../../components/Pane.js'

function SessionInfo({ onDone }: { onDone: () => void }) {
  const remoteSessionUrl = useAppState(s => s.remoteSessionUrl)
  const [qrCode, setQrCode] = useState<string | null>(null)

  // Generate QR code when URL becomes available
  useEffect(() => {
    if (!remoteSessionUrl) return
    qrToString(remoteSessionUrl, {
      type: 'utf8',
      errorCorrectionLevel: 'L',
    }).then(setQrCode)
  }, [remoteSessionUrl])

  // Dismiss on Escape
  useKeybinding('escape', onDone)

  if (!remoteSessionUrl) {
    return <Text color="yellow">No remote session active</Text>
  }

  return (
    <Pane title="Remote Session">
      <Box flexDirection="column" alignItems="center">
        {qrCode && <Text>{qrCode}</Text>}
        <Text color="cyan">{remoteSessionUrl}</Text>
        <Text dimColor>Press ESC to dismiss</Text>
      </Box>
    </Pane>
  )
}

export const call: LocalJSXCommandCall = async (onDone) => {
  return <SessionInfo onDone={onDone} />
}

Example 3: Session Identifier Parsing

// sessionUrl.ts — Accepts 3 formats for session identification
import { parseSessionIdentifier } from '../utils/sessionUrl.js'

// Format 1: JSONL file path
const fromFile = parseSessionIdentifier('/path/to/export.jsonl')
// => { jsonlFile: '/path/to/export.jsonl', isJsonlFile: true, ... }

// Format 2: UUID
const fromUuid = parseSessionIdentifier('550e8400-e29b-41d4-a716-446655440000')
// => { sessionId: '550e8400-...', isUrl: false, isJsonlFile: false }

// Format 3: Remote URL
const fromUrl = parseSessionIdentifier('https://api.example.com/v1/session/abc')
// => { sessionId: 'abc', ingressUrl: 'https://api.example.com', isUrl: true }