Sessions

Starting a New Session

Navigate to the agent's home page and type a message in the composer. Sending it creates a new session, starts the agent's container (if it is not already running), and delivers the message.

Two options are available before sending:

• Model: Opus, Fable, Sonnet, or Haiku. See Model Selection.
• Effort: the thinking effort level. See Effort Level.

These settings are remembered per session; returning to an existing session seeds the composer with the model and effort last used there.

Attach files or folders to the first message with 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 renamed.
• Creation time: a relative timestamp (e.g., "3 hours ago").
• Activity indicators: a pulsing dot marks sessions that are actively processing; an orange dot marks sessions awaiting 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. Typing filters sessions by name, case-insensitively.

Pagination

Agents with many sessions show 10 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 to open the context menu. Available actions depend on your role:

• Rename Session: give the session a custom name (owner only).
• Copy Raw Log: copy the full JSONL transcript to the clipboard, useful for debugging or sharing.
• Delete Session: permanently remove the session and all its messages (owner only). This cannot be undone.

Inside a Session

Clicking a session opens the chat view with the full conversation. Send follow-up messages at any time; if the agent is still working, the message is queued and picked up when the agent is ready.

Message Search

Press Cmd+F (Ctrl+F on Windows/Linux) inside a session to open the find-in-session search bar:

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

Context Window Usage

Each session tracks token usage from the last completed turn, useful for understanding cost and context consumption:

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

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 is a JSON object representing one of:

• User messages: 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. The 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 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

Star a session to protect it from automatic deletion. The star is toggled from the session view and stored in the session metadata.

Session Auto-Delete

Gamut can automatically delete old, inactive sessions to keep the 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 agent.

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

Automated Sessions

Sessions can also be created automatically by:

• Scheduled tasks: a cron schedule or one-time timer.
• Webhook triggers: an incoming HTTP webhook.
• Chat integrations: external chat platforms (e.g., Slack).
• Other agents: one agent invoking another with the multi-agent tool.

Automated sessions are tagged with metadata indicating their origin and appear in the session list alongside manually created ones.