Sessions

A session is a single conversation between you and an agent. Each agent can have many sessions running in parallel, and each session maintains its own message history, context window, and state.

Starting a New Session

To start a new session, navigate to the agent's home page and type a message in the composer. When you send the message, Superagent creates a new session, starts the agent's container (if it is not already running), and delivers your message.

You can configure two options before sending:

• Model -- choose between Opus, Sonnet, or Haiku. See Model Selection.
• Effort -- set the thinking effort level. See Effort Level.

These settings are remembered per session. When you return to an existing session, the composer seeds itself with the model and effort you last used there.

You can also attach files or folders to your first message using the attachment picker, paste images directly, or use voice input.

Session List

All sessions for an agent appear on the agent home page beneath the composer. The list shows:

• Session name -- derived from the first user message (first 50 characters), or a custom name if you have renamed it.
• Creation time -- displayed as a relative timestamp (e.g., "3 hours ago").
• Activity indicators -- a pulsing dot appears next to sessions that are actively processing, and an orange dot for sessions awaiting your input.

Sorting

Click the sort icon above the session list to toggle between Newest first and Oldest first.

Filtering

Click the search icon to open a filter bar. Type to filter sessions by name. The filter matches session names case-insensitively.

Pagination

When an agent has many sessions, the list is paginated with 10 sessions per page. Use the page navigation controls at the bottom to browse older sessions.

Session Actions

Hover over a session row to reveal the actions menu (three-dot icon), or right-click a session to open the context menu. Available actions depend on your role:

• Rename Session -- give the session a custom name (owner only).
• Copy Raw Log -- copies the full JSONL transcript to your clipboard, which is useful for debugging or sharing.
• Delete Session -- permanently removes the session and all its messages (owner only). This action cannot be undone.

Inside a Session

Clicking on a session opens the chat view, where you can read the full conversation and send follow-up messages.

Message Search

Press Cmd+F (or Ctrl+F on Windows/Linux) inside a session to open the find-in-session search bar. This uses the browser's CSS Custom Highlight API to highlight matches directly in the rendered transcript without modifying the DOM.

• Type your query to see matches highlighted in the message list.
• Use Enter to jump to the next match, Shift+Enter for the previous match.
• The counter shows your position (e.g., "3 of 12 matches").
• Click Done or press Escape to close.

Context Window Usage

Each session tracks token usage metadata from the last completed turn:

• Input tokens -- tokens sent to the model.
• Output tokens -- tokens generated by the model.
• Cache creation / read tokens -- tokens related to prompt caching.
• Context window -- total context window size used.

This information is stored in session metadata and can help you understand cost and context consumption.

How Sessions are Persisted

Sessions are stored as JSONL (JSON Lines) files on disk. Each agent has a sessions/ directory, and each session is a single file named {session-id}.jsonl.

Each line in the JSONL file is a JSON object representing one of:

• User messages -- your prompts, file attachments, and tool result responses.
• Assistant messages -- the agent's replies, including text, thinking blocks, and tool calls.
• System entries -- internal markers like compaction boundaries (when the context window is summarized to free space) and memory recall events.

Messages include metadata such as UUIDs, timestamps, parent message references, and model information. This format is compatible with the Claude Code SDK.

Session Metadata

Alongside the JSONL files, a session-metadata.json file stores lightweight metadata for all sessions belonging to an agent:

{
  "session-uuid-1": {
    "name": "Summarize Q4 report",
    "starred": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "effort": "high",
    "model": "opus"
  }
}

This metadata includes the session name, starred status, creation timestamp, the last effort level and model used, and optional fields for scheduled task or webhook trigger context.

Starred Sessions

You can star a session to protect it from automatic deletion. Starred sessions are preserved even when the session auto-delete policy would normally remove inactive sessions.

The starred status is stored in the session metadata and can be toggled from the session view.

Session Auto-Delete

Superagent can automatically delete old, inactive sessions to keep your workspace clean. This is configured at two levels:

1. App-wide default -- set in the global settings. Applies to all agents unless overridden.
2. Per-agent override -- set in the agent's Settings > General tab. Overrides the app default for that specific agent.

Starred sessions are always exempt from auto-deletion. The auto-delete monitor runs periodically and removes sessions that have been inactive for longer than the configured number of days.

Automated Sessions

Sessions can also be created automatically by:

• Scheduled tasks -- sessions triggered by a cron schedule or one-time timer.
• Webhook triggers -- sessions triggered by an incoming HTTP webhook.
• Chat integrations -- sessions created from external chat platforms (e.g., Slack).
• Other agents -- sessions created when one agent invokes another using the multi-agent tool.

These automated sessions are tagged with metadata indicating their origin, and they appear in the session list alongside manually created sessions.