Skip to main content
Maestro’s Session Discovery feature lets you browse and resume AI provider sessions from external sources like Claude Code’s session history. Access conversations from any project, search by content, and resume them in new tabs.

​
Opening the Session Browser

Cmd+Shift+L        # View agent sessions
Shortcut: src/renderer/constants/shortcuts.ts:45-49
Modal Component: src/renderer/components/AgentSessionsModal.tsx

​
Supported Providers

Full SupportMaestro reads Claude Code’s session history from ~/.claude/projects/.

​
What You Get

  • Complete conversation history
  • Token usage statistics
  • Cache hit/creation metrics
  • Cost tracking (USD)
  • Message timestamps
  • Project context

​
Path Encoding

Claude Code encodes project paths by replacing / with -:
/Users/you/Projects/Maestro
→ ~/.claude/projects/-Users-you-Projects-Maestro/
Implementation: src/main/index.ts (IPC handlers)

​
Session Browser Interface

​
Main List View

The session browser displays:
1

Session Cards

Each session shows:
  • First message preview (truncated)
  • Message count (total conversation turns)
  • Last modified (relative time)
  • File size (session data size)
  • Star status (if starred in Maestro)
2

Search Bar

Search sessions by:
  • Message content (searches all messages)
  • Session names (if named in Maestro)
  • User messages only
  • Assistant responses only
IPC Handler: claude:searchSessions
3

Sort Options

Sort by:
  • Recently modified (default)
  • Creation date
  • Message count
  • File size

​
Session Detail View

Click any session to view its full conversation: 
// Session message structure
interface SessionMessage {
  type: string;
  role?: string;           // 'user' | 'assistant'
  content: string;         // Message text or tool output
  timestamp: string;       // ISO 8601 timestamp
  uuid: string;            // Unique message ID
  toolUse?: any;          // Tool call metadata
}
Features:
  • Paginated message loading (20 messages per page)
  • Syntax-highlighted code blocks
  • Tool call cards with expand/collapse
  • Scroll position preservation
  • Copy message content
Component: src/renderer/components/AgentSessionsModal.tsx:238-420

​
Search Capabilities

​
Search Modes

// Search everywhere (default)
const results = await window.maestro.claude.searchSessions(
  projectPath,
  'query',
  'all'
);
Searches both user messages and assistant responses.
IPC Handler: src/main/index.ts → claude:searchSessions

​
Resuming Sessions

When you resume a session, Maestro:
1

Creates New Tab

Opens a fresh AI tab in the current agent.
2

Links Session ID

Associates the tab with the provider session ID:
interface AITab {
  id: string;
  agentSessionId?: string;  // Claude session ID
  // ...
}
3

Loads Context

The AI provider (Claude Code) loads the full conversation history from its session storage.
4

Continues Conversation

You can immediately continue where you left off - all context is preserved.
Pro Tip: Resume the same session in multiple tabs to explore different branches of a conversation without losing the original thread.

​
Global Statistics

View aggregated statistics across all your Claude Code sessions: 
# Open Session Browser, then click "Global Stats" tab

​
Metrics Tracked

interface GlobalStats {
  totalSessions: number;              // Total session count
  totalMessages: number;              // All messages across sessions
  totalInputTokens: number;           // Input token usage
  totalOutputTokens: number;          // Output token usage
  totalCacheReadTokens: number;       // Cache hits
  totalCacheCreationTokens: number;   // Cache writes
  totalCostUsd: number;               // Estimated cost in USD
  totalSizeBytes: number;             // Total storage used
}

​
Streaming Updates

Global stats calculation is progressive - you see results as they’re computed: 
// Subscribe to streaming updates
const unsubscribe = window.maestro.claude.onGlobalStatsUpdate((stats) => {
  console.log(`Progress: ${stats.totalSessions} sessions`);
  console.log(`Cost so far: $${stats.totalCostUsd.toFixed(2)}`);
  
  if (stats.isComplete) {
    console.log('Stats calculation complete!');
  }
});

// Cleanup
unsubscribe();
IPC Handler: src/main/index.ts → claude:getGlobalStats, claude:onGlobalStatsUpdate

​
IPC API Reference

All session discovery features use these IPC handlers:

​
List Sessions

const sessions = await window.maestro.claude.listSessions(projectPath);
// Returns: AgentSession[]
Returns: 
interface AgentSession {
  sessionId: string;
  projectPath: string;
  timestamp: string;         // Creation time
  modifiedAt: string;        // Last modified
  firstMessage: string;      // Preview text
  messageCount: number;
  sizeBytes: number;
  sessionName?: string;      // Custom name from Maestro
  starred?: boolean;         // Star status from Maestro
}

​
Read Messages

const { messages, total, hasMore } = await window.maestro.claude.readSessionMessages(
  projectPath,
  sessionId,
  { offset: 0, limit: 20 }
);
Pagination: Load 20 messages at a time for performance. 
const results = await window.maestro.claude.searchSessions(
  projectPath,
  'search query',
  'all' // 'title' | 'user' | 'assistant' | 'all'
);

​
Global Stats

// One-time fetch
const stats = await window.maestro.claude.getGlobalStats();

// Subscribe to updates
const unsubscribe = window.maestro.claude.onGlobalStatsUpdate((stats) => {
  // Handle progressive updates
});
Source: src/main/preload.ts:203-226

​
Storage Location

​
Claude Code Sessions

~/.claude/projects/{encoded-path}/
├── settings.json
└── sessions/
    ├── {session-id}/
    │   ├── messages.jsonl
    │   ├── metadata.json
    │   └── usage.json
    └── ...

​
Maestro Metadata

~/Library/Application Support/maestro/
├── maestro-sessions.json    # Links sessions to Maestro tabs
└── maestro-settings.json    # Star status, custom names
Maestro never modifies Claude Code’s session files - it only reads them. Your session data remains pristine.

​
Starring Sessions

Mark important sessions with a star:
  1. Click the star icon in the session list
  2. Starred sessions appear at the top
  3. Star status persists in Maestro’s settings
// Star status stored in Maestro settings
starredSessions: Set<string>  // Set of session IDs

​
Keyboard Navigation

Navigate the session browser with keyboard: 
# In Session List
↑/↓               # Select previous/next session
Enter             # Open selected session detail
Esc               # Close browser (or back from detail)

# In Search
Cmd+F             # Focus search input
Esc               # Clear search and refocus list

​
Performance Optimizations

Message content is loaded only when you open a session detail view.The list view shows only metadata (first message, counts, timestamps).
Search uses streaming file reads with line-by-line matching to avoid loading entire sessions into memory.
Global stats are calculated incrementally with UI updates every 100ms to show progress.

​
Next Steps

Agent Management

Create and organize agents

Dual-Mode Sessions

Switch between AI and terminal

File Explorer

Browse files and use @-mentions

Git Integration

Version control features

Build docs developers (and LLMs) love

Get started for freeTalk to us