ada sessions

Browse and manage all session history across chat, agents, and MCP

The sessions command provides a unified interface for browsing, searching, and managing all your interaction history with Ada CLI, including chat conversations, agent executions, and MCP sessions.

Overview

Sessions capture your interaction history with AI systems, allowing you to:

Review past conversations - Browse previous chat sessions
Resume work - Pick up where you left off
Search history - Find specific discussions or solutions
Track progress - See what you've accomplished
Export sessions - Save important conversations

All sessions are stored locally in ~/.lovelace/sessions/ and include:

Full conversation history
Timestamps for every message
Model and provider information
Context files used
Session metadata (tags, descriptions)

Usage

bash

ada sessions [options]

Alias: lovelace s

Options

Display Options

Option	Description	Default
`--interactive`	Force interactive browser mode	Auto-detect TTY
`--table`	Force table output format	Auto-detect
`-j, --json`	Output in JSON format	`false`
`--verbose`	Show detailed session information	`false`

Filtering Options

Option	Description
`-t, --type <type>`	Filter by session type (chat, mcp, agent, all)
`--search <query>`	Search by title, description, or tags
`--tags <tags>`	Filter by tags (comma-separated)
`--servers <servers>`	Filter by MCP servers (comma-separated)
`--providers <providers>`	Filter by AI providers (comma-separated)
`--status <status>`	Filter by status (active, paused, archived, error)
`--min-events <count>`	Show only sessions with minimum event count
`--recent <days>`	Show only sessions from last N days
`--limit <count>`	Maximum number of sessions to show

Sorting Options

Option	Description	Default
`--sort <field>`	Sort by field (created, updated, title, events)	`updated`
`--order <dir>`	Sort direction (asc, desc)	`desc`

Session Loading

Option	Description
`-l, --load <session>`	Load specific session by ID or name

Interactive Examples

Browsing All Sessions

$ ada sessions

Recent Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ID               │ Title                        │ Type  │ Events │ Updated
─────────────────┼──────────────────────────────┼───────┼────────┼────────────
sess_abc123      │ Authentication implementation│ chat  │ 28     │ 2 hours ago
sess_xyz789      │ Code review session          │ chat  │ 15     │ 1 day ago
sess_mcp001      │ Linear issue management      │ mcp   │ 12     │ 1 day ago
sess_agent42     │ Security analysis            │ agent │ 47     │ 3 days ago

Use arrow keys to browse, Enter to view, q to quit

Interactive Browser Mode

When running in a TTY, sessions command launches an interactive browser:

$ ada sessions

┌─ Sessions Browser ───────────────────────────────────────┐
│                                                          │
│ Search: _                                   Filter: All  │
│                                                          │
│ > Authentication implementation (28 messages)            │
│   2025-10-19 • claude-sonnet-4-5 • 2 hours ago          │
│   Tags: auth, security                                   │
│                                                          │
│   Code review session (15 messages)                      │
│   2025-10-18 • gpt-4 • 1 day ago                        │
│   Tags: review, refactoring                              │
│                                                          │
│   Linear issue management (12 commands)                  │
│   2025-10-18 • mcp • 1 day ago                          │
│   Server: linear                                         │
│                                                          │
│   Security analysis (47 steps)                           │
│   2025-10-16 • agent • 3 days ago                       │
│   Status: Completed                                      │
│                                                          │
└──────────────────────────────────────────────────────────┘

Commands: ↑↓ Navigate  Enter View  / Search  f Filter  q Quit

Filtering by Type

$ ada sessions --type chat

Chat Sessions Only
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
sess_abc123      │ Authentication implementation│ 28 msgs │ 2 hours ago
sess_xyz789      │ Code review session          │ 15 msgs │ 1 day ago
sess_def456      │ Bug debugging                │ 8 msgs  │ 2 days ago

$ ada sessions --type mcp

MCP Sessions Only
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
sess_mcp001      │ Linear issue management      │ 12 cmds │ 1 day ago
sess_mcp002      │ File operations              │ 34 cmds │ 2 days ago

$ ada sessions --type agent

Agent Sessions Only
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
sess_agent42     │ Security analysis            │ 47 steps│ 3 days ago
sess_agent43     │ Test generation              │ 23 steps│ 4 days ago

Searching Sessions

$ ada sessions --search "authentication"

Search Results: "authentication"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found 3 matching sessions:

sess_abc123      │ Authentication implementation│ 28 msgs │ 2 hours ago
  Matched in: Title, Messages
  Context: "OAuth setup", "JWT tokens", "session management"

sess_old789      │ Password reset flow          │ 12 msgs │ 1 week ago
  Matched in: Messages
  Context: "authentication error", "reset token"

sess_doc123      │ API documentation            │ 8 msgs  │ 2 weeks ago
  Matched in: Messages
  Context: "authentication endpoints"

Filtering by Tags

$ ada sessions --tags "security,urgent"

Sessions Tagged: security, urgent
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
sess_agent42     │ Security analysis            │ 47 steps│ 3 days ago
  Tags: security, urgent, audit

sess_abc456      │ Fix SQL injection            │ 18 msgs │ 1 week ago
  Tags: security, urgent, bug-fix

Recent Sessions

$ ada sessions --recent 7

Sessions from Last 7 Days
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
sess_abc123      │ Authentication implementation│ 28 msgs │ 2 hours ago
sess_xyz789      │ Code review session          │ 15 msgs │ 1 day ago
sess_mcp001      │ Linear issue management      │ 12 cmds │ 1 day ago
sess_agent42     │ Security analysis            │ 47 steps│ 3 days ago
sess_def456      │ Bug debugging                │ 8 msgs  │ 5 days ago

5 sessions in the last 7 days

JSON Output

bash

$ ada sessions --limit 2 --json

[
  {
    "id": "sess_abc123",
    "type": "chat",
    "title": "Authentication implementation",
    "description": "Discussion about OAuth and JWT setup",
    "provider": "anthropic",
    "model": "claude-sonnet-4-5",
    "eventCount": 28,
    "created": "2025-10-19T12:00:00.000Z",
    "updated": "2025-10-19T14:30:00.000Z",
    "tags": ["auth", "security", "oauth"],
    "contextFiles": [
      "src/auth/login.ts",
      "src/auth/session.ts"
    ]
  },
  {
    "id": "sess_xyz789",
    "type": "chat",
    "title": "Code review session",
    "provider": "openai",
    "model": "gpt-4",
    "eventCount": 15,
    "created": "2025-10-18T10:00:00.000Z",
    "updated": "2025-10-18T11:15:00.000Z",
    "tags": ["review", "refactoring"]
  }
]

Loading a Specific Session

$ ada sessions --load sess_abc123

Loading Session: sess_abc123
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title: Authentication implementation
Type: chat
Provider: Anthropic Claude (claude-sonnet-4-5)
Created: 2025-10-19 12:00
Updated: 2025-10-19 14:30
Events: 28 messages
Tags: auth, security, oauth

Context Files (3):
  • src/auth/login.ts
  • src/auth/session.ts
  • src/types/user.ts

Recent Messages:
─────────────────────────────────────────────────
[12:05] You: How does authentication work?

[12:06] AI: Based on your code in src/auth/login.ts...

[12:10] You: Can you explain the session callback?

[12:11] AI: The session callback does two things...

[... full conversation history ...]

─────────────────────────────────────────────────

Resume this session with:
  ada chat --load sess_abc123

Subcommands

`ada sessions clear`

Delete sessions to free up space or remove old history.

Usage:

bash

ada sessions clear [options]

Aliases: rm

Options:

Option	Description
`--all`	Delete ALL sessions (requires confirmation)
`--force`	Skip confirmation prompts
`--threads-only`	Delete only metadata, keep conversation history
`--events-only`	Delete only history, keep metadata

Interactive Example:

$ ada sessions clear --all

⚠️  WARNING: Delete ALL Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
This will permanently delete:
  • 47 chat sessions
  • 12 MCP sessions
  • 8 agent sessions
  • All conversation history
  • All session metadata

This action CANNOT be undone!

Type 'delete all sessions' to confirm: _

Selective deletion:

$ ada sessions clear --threads-only

Clearing session metadata...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Deleted 67 session metadata files
✓ Kept conversation history intact

Session threads cleared, but messages preserved.
You can still search message history.

Common Use Cases

Review Recent Work

Check what you've been working on:

$ ada sessions --recent 1

Today's Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
sess_abc123      │ Authentication work          │ 28 msgs │ 2 hours ago
sess_xyz789      │ Code review                  │ 15 msgs │ 4 hours ago

2 sessions today

Find Past Solutions

Search for specific topics:

$ ada sessions --search "error handling"

[Found 5 sessions discussing error handling]

$ ada sessions --load sess_old456

[Review how you solved error handling previously]

Track Project Progress

See all sessions for a project:

$ ada sessions --tags "client-dashboard" --sort created --order asc

Project Timeline: client-dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Week 1:
  • Initial setup and architecture
  • Database schema design

Week 2:
  • API implementation
  • Authentication setup

Week 3:
  • Frontend components
  • Code reviews

[Complete project history...]

Clean Up Old Sessions

Remove outdated sessions:

# Review old sessions first
$ ada sessions --recent 90 --limit 100

# Delete specific old sessions
$ ada sessions clear --force --older-than 90

Session Types

Chat Sessions

Interactive AI conversations:

Full message history
Context files used
Model and temperature settings
Session duration

MCP Sessions

Model Context Protocol interactions:

Tool calls executed
Server connections
Command results
Resource access logs

Agent Sessions

Autonomous agent executions:

Task steps performed
Progress checkpoints
Output artifacts
Completion status

Session Storage

Sessions are stored in:

~/.lovelace/sessions/
├── chat/
│   ├── sess_abc123/
│   │   ├── metadata.json
│   │   └── messages.json
│   └── sess_xyz789/
│       ├── metadata.json
│       └── messages.json
├── mcp/
│   └── sess_mcp001/
│       ├── metadata.json
│       └── commands.json
└── agents/
    └── sess_agent42/
        ├── metadata.json
        ├── steps.json
        └── artifacts/

Tips & Best Practices

Tag Your Sessions

Add tags during chat to make sessions searchable:

$ ada chat

You: /tag authentication oauth

✓ Tagged session: authentication, oauth

Regular Cleanup

Remove old sessions periodically:

bash

# Monthly cleanup
ada sessions --older-than 30 --limit 1000
# Review list, then clear if needed
ada sessions clear --older-than 30

Export Important Sessions

Save critical conversations:

bash

ada sessions export sess_abc123 --format markdown > important-discussion.md

Search Effectively

Use specific terms:

✅ ada sessions --search "JWT authentication bug"
❌ ada sessions --search "code"  # Too broad

Exit Codes

Code	Meaning
`0`	Command succeeded
`1`	Error listing or loading sessions
`2`	Invalid arguments

Troubleshooting

No Sessions Found

$ ada sessions

📁 No sessions found

Start a chat to create your first session:
  ada chat

Session Not Loading

$ ada sessions --load nonexistent

Error: Session not found: nonexistent

List available sessions:
  ada sessions

Corrupted Session Data

$ ada sessions

Warning: 2 corrupted sessions detected
  • sess_broken1 (invalid JSON)
  • sess_broken2 (missing metadata)

These sessions will be skipped.
Run cleanup: ada sessions clear --corrupted

Related Commands

ada chat - Start new chat sessions
ada agents - View agent execution sessions
lovelace mcp - MCP session history

Related Guides

Interactive Chat Guide - Session management features
Hackathon Project Example - Tracking project sessions

See the Command Reference for all available commands.