Sessions

Every conversation and task in Opta is tracked as a session. Use the sessions command group to list, inspect, export, and manage your session history.

Overview

Sessions are the fundamental unit of interaction in Opta. Each opta chat or opta do invocation creates a new session (or resumes an existing one). Sessions persist all messages, tool calls, tool results, and metadata to disk so you can review, export, or continue them later.

Listing Sessions

opta sessions list shows all stored sessions, sorted by most recent first. Each entry displays the session ID, title (auto-generated from the first message), creation date, and message count.

ID          Title                          Created           Messages
abc12345    Refactor auth module           2 hours ago       24
def67890    Add JWT validation             Yesterday         18
ghi11223    Fix TypeScript errors          3 days ago        12
jkl44556    Write API documentation        5 days ago        31

Viewing a Session

opta sessions show displays the full contents of a session, including all messages, tool calls, and results. Use this to review what happened in a previous conversation or task.

Exporting Sessions

opta sessions export writes a session to a file in JSON format. This is useful for sharing sessions, archiving important conversations, or processing session data with external tools.

Exported to ./opta-session-abc12345.json

Deleting Sessions

opta sessions delete permanently removes a session from disk. This action cannot be undone.

Session abc12345 deleted.

Storage Location

Sessions are stored as JSON files in the daemon's configuration directory. Each session gets its own subdirectory containing the session data and any associated metadata.

~/.config/opta/sessions/
├── abc12345/
│   ├── session.json        # Messages, tool calls, metadata
│   └── metadata.json       # Title, timestamps, stats
├── def67890/
│   ├── session.json
│   └── metadata.json
└── ...

Session Format

Sessions are stored as JSON, following the daemon v3 protocol schema. Each session contains an array of events including user messages, assistant responses, tool calls, and tool results.

{
  "sessionId": "abc12345",
  "title": "Refactor auth module",
  "createdAt": "2026-03-01T10:30:00Z",
  "updatedAt": "2026-03-01T11:15:00Z",
  "events": [
    {
      "type": "user.message",
      "content": "Refactor the auth module to use JWT",
      "seq": 1
    },
    {
      "type": "assistant.message",
      "content": "I'll refactor the auth module...",
      "seq": 2
    },
    {
      "type": "tool.call",
      "toolName": "read_file",
      "args": { "path": "src/auth/index.ts" },
      "seq": 3
    }
  ]
}

Cross-Client Continuity

Sessions created in the CLI are accessible from any Opta client that connects to the same daemon. This means you can start a conversation in the CLI, then continue it in the Opta Local Web interface or the Opta Code Desktop app.