Session Management

​

Overview

​

Key Capabilities

​

Session Types

interface Session {
  id: string                  // UUID v4 identifier
  worktree_id: string         // Parent worktree
  name: string                // Display name
  created_at: number          // Unix timestamp
  updated_at: number          // Last activity
  messages: ChatMessage[]     // Conversation history
  model: ClaudeModel          // opus | sonnet | haiku | etc.
  thinking_level: ThinkingLevel  // off | think | megathink | ultrathink
  effort_level?: EffortLevel  // low | medium | high | max (Opus 4.6 only)
  backend: CliBackend         // claude | codex | opencode
  provider?: string           // Custom provider profile
  archived_at?: number        // Archived timestamp
}

• Created automatically with base worktree
• Represents work on the default branch
• Cannot be deleted (only archived)
• Persists across app restarts

​

Canvas Views

• Grid or list layout (configurable)
• Shows all sessions for active worktree
• Quick keyboard navigation (arrow keys)
• Visual status indicators

• Grouped by worktree with section headers
• Overview of entire project
• Jump between worktrees quickly
• Same grid/list layouts

type CanvasLayout = 'grid' | 'list'

// Grid: Card-based layout with previews
// List: Compact rows for many sessions

• Arrow keys: Navigate between sessions
• Enter: Open selected session
• Cmd/Ctrl + shortcuts: Open plan, recap, approve plan

​

Session Lifecycle

1. User creates new session
2. Session initialized with default model/settings
3. Inherits project-specific configuration
4. Empty message history
5. Automatically named on first message (if enabled)

• Messages appended to history
• State persisted to disk continuously
• UI state tracked (answered questions, fixed findings)
• MCP servers loaded on demand
• Terminals attached to session

• Soft delete - can be restored
• Moves to archive view
• Freed from memory but data preserved
• Subject to retention policy

• After retention period expires
• Manual deletion from archive
• All messages and state lost
• Cannot be recovered

​

Session Modes

// User message includes plan mode marker
const message = "Fix the authentication bug [plan]"

// AI responds with plan
// User reviews and approves
// AI executes approved plan

• Similar to plan mode
• Different model/settings can be configured
• Approval required before changes

• No approval needed
• Fastest iteration
• Use for trusted operations

• Append [plan], [build], or [yolo] to message
• Or use toolbar buttons
• Per-message choice

​

Auto-Naming

interface AppPreferences {
  auto_session_naming: boolean           // Enable/disable
  session_naming_model: ClaudeModel      // Model to use
  magic_prompts: {
    session_naming: string | null        // Custom prompt
  }
}

const DEFAULT_SESSION_NAMING_PROMPT = `<task>Generate a short, human-friendly name for this chat session based on the user's request.</task>

<rules>
- Maximum 4-5 words total
- Use sentence case (only capitalize first word)
- Be descriptive but concise
- Focus on the main topic or goal
- No special characters or punctuation
- No generic names like "Chat session" or "New task"
- Do NOT use commit-style prefixes like "Add", "Fix", "Update", "Refactor"
</rules>

<user_request>
{message}
</user_request>

<output_format>
Respond with ONLY the raw JSON object, no markdown, no code fences:
{"session_name": "Your session name here"}
</output_format>`

• “Implement user authentication” → “User authentication system”
• “Fix bug in payment processing” → “Payment processing bug”
• “Refactor database queries” → “Database query optimization”

​

Session Recap (Digest)

interface AppPreferences {
  session_recap_enabled: boolean  // Default: false (experimental)
}

• Returning to unfocused session
• After significant time gap
• Helps regain context quickly

interface SessionDigest {
  chat_summary: string      // One sentence, max 100 chars
  last_action: string       // Last completed task, max 200 chars
}

​

State Persistence

• Messages: <worktree_path>/.jean/sessions/<session_id>/messages.json
• State: <worktree_path>/.jean/sessions/<session_id>/state.json
• Attachments: <worktree_path>/.jean/sessions/<session_id>/attachments/

interface UIState {
  answered_questions: Record<string, Set<string>>  // sessionId → question IDs
  fixed_review_findings: Record<string, Set<string>>  // sessionId → finding IDs
  loaded_issue_numbers: Record<string, number[]>    // sessionId → issue numbers
  loaded_pr_numbers: Record<string, number[]>       // sessionId → PR numbers
  // ... more UI-specific state
}

1. Zustand store holds UI state
2. Hook subscribes to changes
3. Debounced save to Tauri backend
4. Restored on session load

​

How to Use

​

Creating Sessions

1. Click ”+” in chat tabs bar
2. New session created with default settings
3. Start chatting immediately

1. Press Cmd/Ctrl + K to open canvas
2. Click “New Session” button
3. Session created in current worktree

​

Switching Between Sessions

• Click session tabs at top of chat
• Cmd/Ctrl + 1-9 for quick switching
• Cmd/Ctrl + [ and ] for prev/next

• Cmd/Ctrl + K to open canvas
• Arrow keys to move selection
• Enter to open session
• Escape to close canvas

​

Session Settings

• Toolbar dropdown
• Choose from available models
• Settings persist for session

• Off: No extended thinking
• Think: 4K thinking tokens
• Megathink: 10K thinking tokens
• Ultrathink: 32K thinking tokens

• Low: Minimal reasoning
• Medium: Moderate depth
• High: Deep analysis
• Max: Unlimited reasoning

• Change CLI backend (Claude/Codex/OpenCode)
• Select provider profile for API routing
• Per-session configuration

​

Managing Session History

• Scroll through chat history
• Syntax-highlighted code blocks
• Expandable thinking sections
• File previews and diffs

• Toolbar → More → Clear Context
• Creates new session
• Optionally closes original
• Useful for starting fresh

• Toolbar → Save Context
• AI summarizes conversation
• Saved as markdown file
• Can load in future sessions

​

Archiving Sessions

1. Right-click session tab → Archive
2. Or use canvas context menu
3. Confirmation dialog (if enabled)
4. Moves to archive

1. Open Archive modal (Cmd/Ctrl + Shift + A)
2. Sessions grouped by worktree
3. Filter and search
4. Restore or permanently delete

1. Find in archive modal
2. Click “Restore”
3. Returns to active sessions
4. All state preserved

​

Canvas Workflow

• Settings → Interface → Canvas Layout
• Grid: Visual cards with previews
• List: Compact rows for many sessions

• Session name and timestamp
• Last message preview
• Status badges (waiting, thinking, error)
• Model and mode indicators

• Denser information display
• More sessions visible at once
• Quick scanning
• Same functionality as grid

​

Configuration Options

​

Settings → Sessions

auto_session_naming: boolean           // Enable automatic naming
session_naming_model: ClaudeModel      // Model for name generation

session_recap_enabled: boolean         // Show digest on return

confirm_session_close: boolean         // Warn before closing

archive_retention_days: number         // 0 = never delete

​

Settings → Interface

canvas_layout: 'grid' | 'list'        // View mode

show_keybinding_hints: boolean         // Show shortcuts at bottom

​

Best Practices

​

Session Organization

• Keep sessions focused
• Create new session for different work
• Avoid mixing unrelated topics

Worktree: fix-auth-bug
  ├─ fix-auth-bug (base session) - Main implementation
  ├─ testing-strategy - Test planning  
  └─ code-review - Pre-PR review

​

Context Management

• Hit token limits
• Change direction significantly
• Start new feature in same worktree
• Performance degrades

• Before major refactoring
• End of work session
• Before asking team for help
• Documenting decisions

​

Canvas Usage

• Visual thinkers
• Fewer sessions (< 20)
• Quick status overview
• Session preview helpful

• Many sessions (20+)
• Fast scanning
• Keyboard-heavy workflow
• Information density priority

​

Archive Management

• Archive: Temporary pause, might return
• Delete: Definitely done, save space

• 7 days: Active projects, fast iteration
• 30 days: Reference needed for similar work
• Never: Audit trail required

​

Model Selection

• Opus: Complex problems, architecture decisions
• Sonnet: General development, code review
• Haiku: Quick questions, simple refactors

• Off: Fast, deterministic tasks
• Think: Standard reasoning
• Megathink: Complex logic, edge cases
• Ultrathink: Novel problems, research

​

Performance Optimization

• Archive finished work
• Don’t load unnecessary context
• Clear old thinking traces
• Use file mentions instead of pasting code

• Active sessions per worktree: 10-15
• Messages per session: < 100
• Token count: < 100K

​

Recovery

• Jean auto-saves continuously
• Restart app to recover
• Check logs in debug panel
• Report crash with logs

• Check .jean/sessions/ directory
• messages.json files are readable
• Can manually reconstruct
• Future: built-in export