lovelace 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 Lovelace 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

lovelace 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

$ lovelace 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:

$ lovelace 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

$ lovelace 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

$ lovelace 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

$ lovelace 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

$ lovelace 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

$ lovelace 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

$ lovelace 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

$ lovelace 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

$ lovelace 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:
  lovelace chat --load sess_abc123

Subcommands

`lovelace sessions clear`

Delete sessions to free up space or remove old history.

Usage:

bash

lovelace 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:

$ lovelace 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:

$ lovelace 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:

$ lovelace 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:

$ lovelace sessions --search "error handling"

[Found 5 sessions discussing error handling]

$ lovelace sessions --load sess_old456

[Review how you solved error handling previously]

Track Project Progress

See all sessions for a project:

$ lovelace 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
$ lovelace sessions --recent 90 --limit 100

# Delete specific old sessions
$ lovelace 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:

$ lovelace chat

You: /tag authentication oauth

✓ Tagged session: authentication, oauth

Regular Cleanup

Remove old sessions periodically:

bash

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

Export Important Sessions

Save critical conversations:

bash

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

Search Effectively

Use specific terms:

✅ lovelace sessions --search "JWT authentication bug"
❌ lovelace 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

$ lovelace sessions

📁 No sessions found

Start a chat to create your first session:
  lovelace chat

Session Not Loading

$ lovelace sessions --load nonexistent

Error: Session not found: nonexistent

List available sessions:
  lovelace sessions

Corrupted Session Data

$ lovelace sessions

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

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

Related Commands

lovelace chat - Start new chat sessions
lovelace 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.