↑ ↓ to move · Enter to open · Esc to close Something not working? Troubleshooting
    On this page

    Browse AI Agent Sessions and Saved Summaries

    A session groups related activity: the commands from one terminal, or one conversation with an AI coding agent. suv sessions shows both kinds in one local browser. For supported agents it shows prompts, assistant responses, commands, observed models, reported token counts, and any summaries an agent saved. This page describes Suvadu 0.4.1.

    Quick start: run suv sessions, type to filter, press Enter to open a session, and press s on an AI session to read its saved summaries. For scripts, use suv agent sessions and suv agent session <id>, which print JSON.

    What a session contains

    The picker's Type column shows Human or AI. These labels cover three different sources of data:

    Shell sessions

    Each shell that loads the Zsh or Bash hook gets a session ID when it starts. That ID is stored in the SUVADU_SESSION_ID environment variable. A shell session contains only commands. Each command has its directory, exit code, start and end time, duration, and executor. If every command in the session was classified as human-typed, the picker shows it as Human.

    Command-backed agent sessions

    A shell session is shown as AI when at least one of its commands was recorded with a non-human executor. For example, the command may have come from an agent hook or from an agent's integrated terminal. Cursor, pi.dev, and Antigravity activity appears this way. Cursor and pi.dev can attach the prompt text that was active when a command ran. These sessions contain only commands and have no model or token data.

    Native agent sessions

    For Claude Code, Codex, and OpenCode, Suvadu also imports the agent's own session record. That record includes user prompts, assistant responses, interrupted turns, the models the agent recorded, and token usage reported by the provider. Commands the agent ran through its shell tool are matched to the same session. A native session can show a conversation even when no commands ran. Native session IDs start with claude-, codex-, or opencode-, followed by the agent's own session ID.

    Suvadu does not store Claude Code thinking blocks, attachments, images, file contents, or raw tool results. For Codex, developer instructions, injected context, commentary, and reasoning are excluded. Each session's metadata includes a coverage note. The note says the session combines captured transcript events and locally recorded shell commands only. Child sessions and non-shell tools are not included.

    Which integrations capture sessions

    Session content depends on how the agent was connected. The table is a summary from a source review on 19 September 2026. See Compatibility for the full matrix, the versions the project says it tested, and known gaps. Use Agent Setup for setup steps.

    Setup commandWhat suv sessions can showWhen content arrives
    suv init claude-codeNative session: prompts, responses, models, reported tokens, and Bash-tool commandsCommands when they run; conversation at the agent's Stop and SessionEnd hooks
    suv init codexNative session: prompts, final answers, models, reported tokens, and shell commandsCommands when the hook fires; conversation at Stop and SessionEnd. Codex must trust the hooks first.
    suv init opencodeNative session: prompts, responses, model, reported tokens, and bash commandsCommands when they run; conversation when the OpenCode session goes idle
    suv init cursorCommands, each with the conversation's latest prompt attachedAfter each shell execution
    suv init piCommands, each with the prompt text attached (the extension keeps the first 500 characters)After each bash tool result
    suv init antigravity, and other detected agentsCommands run in a shell that loaded Suvadu's Zsh or Bash hookWhen the shell prompt returns

    After you run a setup command, relaunch the agent. For an agent's VS Code extension, fully quit and reopen VS Code. Codex also requires you to review and trust Suvadu's hooks in /hooks in the Codex terminal CLI.

    Browse with suv sessions

    suv sessions                     # interactive picker: shell and AI sessions, newest activity first
suv sessions claude-8f2c         # open one session directly by ID or ID prefix
suv sessions --list              # print a table and exit (50 rows by default)
suv sessions --list -n 200       # print more rows
suv sessions --after "7 days ago" --tag work
    Argument / flagMeaning
    [SESSION_ID]Session ID or unique prefix. With no ID, the picker opens. If a prefix matches more than one session, Suvadu lists up to 10 matches and asks for a longer prefix.
    --listPrint sessions and exit without opening the TUI. Columns: last active, ID (first 8 characters), type, tag, agent or host, model, tokens, command count, and duration.
    --after <date>Only sessions with activity on or after this date. Accepts today, yesterday, N days ago, or YYYY-MM-DD.
    --tag <name>Only sessions associated with this tag (see Tags).
    -n, --limit <N>Maximum sessions to load. The picker loads all sessions by default; --list defaults to 50.

    suv session is an alias for suv sessions. The --list table shortens IDs to 8 characters. That prefix may not identify one session, for example when many IDs start with codex-. To see full native session IDs, run suv agent sessions.

    Picker controls

    KeyAction
    Type any textSearch across session ID, tag, agent, observed models, host name, and working directory
    ↑ / ↓Move the selection; continues across pages
    ← / → (or Page Up / Page Down)Previous or next page
    EnterOpen the selected session. Closing the timeline returns to the picker.
    Ctrl+FFilter panel for tag, start date, and end date. Tab moves between fields, Enter applies, and Esc discards changes.
    Ctrl+TCycle the type filter: All → Human → AI
    Ctrl+XClear the tag, date, and type filters (shown when a filter is active)
    EscQuit

    AI session timeline

    A native session opens with a header and a timeline. The header shows the agent, model, number of prompts, number of commands, duration, and tokens. The timeline lists Prompt, Command, Response, and Interrupted items in time order. At the same timestamp, Suvadu orders them prompt, then command, then response. Each row shows the time, type, a text preview, the directory, and either the model or the command's status.

    KeyAction
    ↑↓ or jkMove through items
    ←→Previous or next page
    g / GFirst or last item
    TabShow or hide the detail panel (full text, source ID, path, turn, model; for commands: linked prompt, exit code, duration, executor)
    Ctrl+YCopy the selected item's text or command
    EnterOn a command with a linked prompt, open it in the Prompt Explorer
    sOpen saved summaries (see View summaries)
    q / EscBack

    Shell sessions and command-backed agent sessions open the command timeline instead. It has the same navigation, Tab, and Ctrl+Y keys. Pressing s there reports that summaries are only available for AI sessions. For a plain chronological list of commands, see Session Replay.

    Reading missing or unknown values

    You seeIt means
    — in the Model or Tokens column of --listThe session has no native record, or no model or usage was reported. The value is unknown, not zero.
    unknown model / unknown agentThe imported events did not name a model or agent
    Tokens unavailableNo usable token-usage record was captured
    • partial after the token figuresSome transcript records were skipped, for example while recording was paused or disabled for that directory. Totals can be incomplete.
    Status •, or exit unknown in the detail panelThe integration did not report an exit code. Codex omits one when its payload has no structured exit code.
    +N after a model nameThe session recorded N more models. The latest observed model is shown first.
    A No captured conversation items messageThe native session exists but has no prompts, responses, or commands in Suvadu yet

    Some values are approximate. Codex command timestamps record when the hook was received, so Codex command durations are not measured. Cursor reports exit code 0 when its payload has no exit code. The pi.dev extension records failed bash calls as exit code 1 unless pi reports a more specific code.

    JSON commands for scripts and agents

    suv agent sessions [--limit N] [--offset N]            # native sessions, newest first (limit 1-100, default 20)
suv agent session <id> [--limit N] [--offset N]        # events, commands, usage, revision, and summaries (limit 1-100, default 50)
suv agent import-session <path-to-transcript.jsonl>    # import a Codex or Claude Code JSONL transcript
suv agent delete-session <id>                          # delete one native session (see below)

    These commands cover native sessions only. Output is paginated: follow next_offset until it is null. import-session detects whether the file is from Codex or Claude Code. It imports only records it has not seen before, so running it again on a growing transcript is safe. It does not accept OpenCode data; OpenCode sessions arrive through the plugin. suv agent session needs the full session ID; it does not accept a prefix.

    Try it with a synthetic session

    You can test the session browser without running an agent. Import this small Codex-format transcript, open it, then delete it. Run these commands in a shell where recording is not paused. Paused capture stores the import position but not the content.

    cat > /tmp/suvadu-demo.jsonl <<'EOF'
{"timestamp":"2026-09-19T10:00:00Z","type":"session_meta","payload":{"id":"suvadu-demo","cwd":"/tmp/suvadu-demo"}}
{"timestamp":"2026-09-19T10:00:01Z","type":"turn_context","payload":{"turn_id":"turn-1","cwd":"/tmp/suvadu-demo","model":"demo-model"}}
{"timestamp":"2026-09-19T10:00:02Z","type":"event_msg","payload":{"type":"user_message","message":"Run the synthetic check"}}
{"timestamp":"2026-09-19T10:00:05Z","type":"event_msg","payload":{"type":"token_count","info":{"total_token_usage":{"input_tokens":100,"cached_input_tokens":40,"output_tokens":20,"reasoning_output_tokens":10,"total_tokens":120}}}}
{"timestamp":"2026-09-19T10:00:06Z","type":"event_msg","payload":{"type":"agent_message","phase":"final_answer","message":"The synthetic check passed."}}
EOF

suv agent import-session /tmp/suvadu-demo.jsonl   # JSON result: "session_id": "codex-suvadu-demo"
suv sessions --list                               # row: codex-su  AI  openai-codex  demo-model  120  0
suv sessions codex-suvadu-demo                    # timeline: Prompt, then Response; Tokens 120 total
suv agent delete-session codex-suvadu-demo        # remove the demo session
rm /tmp/suvadu-demo.jsonl

    Reported tokens and observed models

    Suvadu does not count tokens or identify models itself. It copies the values from the agent's own session record:

    • Codex reports running totals. Suvadu shows the latest total and does not add successive updates together.
    • Claude Code usage is deduplicated. Cache-read and cache-creation tokens are counted in total input. The raw session data (suv agent session or the MCP get_agent_session tool) keeps them separate. The suv sessions header shows only cache-read tokens.
    • OpenCode reports usage for each response. Suvadu adds these up across the session.
    • Models are the model names written in the session's events. The header shows the latest model, and +N means N more models appeared.
    • The header always shows the total. It adds input and output on terminals at least 78 columns wide, and cached and reasoning tokens at 100 columns or wider.

    These figures do not establish:

    • Cost or billing. Suvadu has no pricing data. Its totals may differ from your provider's invoice.
    • Complete usage. Child or sub-agent sessions, non-shell tools, records skipped while capture was paused or disabled, and turns still in progress are not included.
    • Which model actually answered. A model name is what the agent recorded, not a verified fact about the provider.
    • Usage for command-only integrations. Cursor, pi.dev, Antigravity, and shell-detected agents have no model or token data in Suvadu.

    Save a summary through your connected agent

    Suvadu never writes summaries and never calls a model. A connected agent reads the session through Suvadu's MCP server, writes the summary, and saves it with the save_session_summary tool. Saving is off by default. In 0.4.1, the suv settings screen does not offer this option, so you edit the configuration file directly.

    1. Open the global configuration file:

      • macOS: ~/Library/Application Support/tech.appachi.suvadu/config.toml
      • Linux: ~/.config/suvadu/config.toml (or $XDG_CONFIG_HOME/suvadu/config.toml)

      When the file exists, suv doctor prints its path on the Config line. A project-level .suvadu.toml file does not change MCP settings.

    2. Add the setting to the [mcp] section. If the file already has an [mcp] section, add the line there instead of creating a second section.

      [mcp]
allow_session_summaries = true

      If save_session_summary appears in mcp.disabled_tools, remove it.

    3. Restart the agent or reconnect its MCP server. The MCP server reads the configuration once at startup, and it only lists save_session_summary when saving is enabled. A connection opened before your edit keeps the old setting.
    4. Ask the agent something like "Summarize and save the current session." The agent finds the session with resolve_current_agent_session and reads every page with get_agent_session. It then calls save_session_summary. If more than one session could match, it gets a list of candidates instead of guessing, and it should ask you to choose.

    Suvadu checks each save and rejects it unless all of these are true:

    • The summary cites the session's current revision. If the session changed while the agent was reading it, the save is rejected and the agent must read it again.
    • It cites between 1 and 1,000 event or command IDs, and all of them belong to that session.
    • The text is at most 16,000 characters and at most 64,000 bytes.

    The agent and model shown on a saved summary are what the calling agent said about itself. Suvadu does not verify them. The current turn is usually imported when the turn ends (Stop, SessionEnd, or OpenCode's idle event), so a summary written mid-turn may miss the latest activity.

    With summaries enabled, suv init claude-code and suv skills sync also install a built-in suvadu-session-memory skill. It tells agents to use these tools when you ask them to summarize a session. See Shared Skills.

    View summaries

    Open an AI session in suv sessions and press s. If no summary is saved yet, the footer says so. Otherwise, the summary overlay opens on the newest saved summary.

    KeyAction
    ↑↓ or jkScroll
    TabSwitch between rendered text and raw Markdown
    Ctrl+YCopy the raw Markdown
    [ / ]Older or newer saved summary (shown when a session has more than one)
    q / EscClose the overlay

    The overlay's header shows CURRENT or STALE and the version number, such as v1 of 3. The next line shows the declared agent, model, and save time. CURRENT means nothing in the session has changed since the summary was saved. STALE means something changed: new prompts, responses, or commands arrived, or a recorded command was edited or deleted.

    Incremental checkpoints and stale evidence

    A saved summary also works as a checkpoint for the next summary. suv agent session <id> and the MCP get_agent_session tool report these fields for each summary:

    FieldMeaning
    currentThe session has not changed since the summary was saved
    has_new_activityNew events or commands were added after it, and the earlier records it covered are unchanged
    incremental_safeThe summary is current or has only new activity after it, so an agent can extend it
    resume_event_offset, resume_command_offsetWhere an agent should start reading new activity when it extends the summary
    staleRecords the summary covered have changed or disappeared. The agent must rebuild the summary from the whole session.

    To extend a checkpoint, an agent passes base_summary_id and keeps every evidence ID from the earlier summary. Suvadu rejects the save if the earlier records no longer match. The TUI is simpler: a checkpoint with new activity is safe to extend, but the overlay still labels it STALE. In the TUI, stale means "not up to date", not "unsafe to extend".

    Missing sessions, prompts without commands, and incomplete capture

    • A native session is missing, or its latest turn is missing. The conversation is imported when a turn ends, not while it is running. Finish a turn, then run suv agent sessions. If it is still missing, see An integration records commands but not prompts or sessions. For Claude Code or Codex, you can import the transcript file yourself with suv agent import-session.
    • Prompts that ran no commands. Native sessions (Claude Code, Codex, OpenCode) keep these prompts and show them in the timeline. The Prompt Explorer lists only prompts that have commands. Cursor and pi.dev attach prompts to commands, so a prompt that ran no commands leaves no record.
    • A gap in the middle of a session. Suvadu skips records while recording is paused (SUVADU_PAUSED) or disabled for a directory, and it does not add them back after you resume. Records that match your exclusion patterns are also left out. The token line may show partial.
    • Text ends in "...". Prompt and response text is redacted and shortened to agent.prompt_capture_max_chars characters (default 4000).
    • Agent commands are missing from search. Search and Up-arrow recall hide agent commands by default. See Agent commands are hidden by recall filters.

    Data storage, access, deletion, and backup

    • Where it lives. Session data is stored in the same local SQLite database as your command history. suv status prints its path. The defaults are ~/Library/Application Support/tech.appachi.suvadu/history.db on macOS and ~/.local/share/suvadu/history.db on Linux. On Unix, Suvadu makes the data directory readable only by your user (permissions 0700). Nothing is uploaded. See Privacy.
    • Who else can read it. A connected agent can read sessions through the MCP server, and its client may send what it reads to the client's model provider. Sessions and commands from directories listed in mcp.exclude_dirs are hidden from MCP tools. The suv commands on this page still show them to you. See MCP Server.
    • Delete one native session. suv agent delete-session <full-id> deletes the session's imported events, its saved summaries, its import position, and every recorded command with that session ID. It leaves the agent's own transcript files alone. Unlike suv delete, it does not make an automatic backup first, so run suv backup before you delete. The import position is deleted too. If that agent session's hooks run again, or you run suv agent import-session on its transcript, Suvadu imports the whole transcript again from the beginning.
    • Delete commands by pattern or date. See Delete & Cleanup.
    • Back up and restore. suv backup saves a consistent snapshot of the whole database, including sessions and summaries. See Backup for how to restore it.
    Found an issue? Report it on GitHub Edit on GitHub