---
title: Sessions, resume and export
description: Where venom keeps sessions, how to continue, resume, search, replay, export, share and attach to them, and how to find the ones that went wrong.
section: cli
order: 70
audience: [user, operator, agent]
sources: [cli/src/resume.ts, cli/src/export-cli.ts, cli/src/export-traces-cli.ts, cli/src/session-cli.ts, cli/src/attach.ts, cli/src/triage.ts, cli/src/library-command.ts, docs/long-tasks.md]
features: [cli.export, cli.export-traces, cli.session, cli.attach, cli.triage]
---

Every session is saved as a JSONL file under `~/.venom/agent/sessions/`, grouped by the directory it started in (`VENOM_CODING_AGENT_SESSION_DIR` or `--session-dir` moves them; `--no-session` saves nothing). A session holds the messages, tool calls and results, model changes and venom's own entries (permission decisions, checkpoints, the call meter), so it can be continued, replayed or exported later.

```bash
venom -c                         # continue the newest session of this directory
venom -r                         # pick one from a list
venom resume                     # continue a task a crash or a usage limit interrupted
venom sessions search flaky test # find a session by its summary
venom export latest              # the full trace as one HTML file
venom session share latest       # redacted, on Venom Cloud for your organisation
```

## Continue and resume {#resume}

| Command | What it does |
|---|---|
| `venom -c`, `venom --continue` | Continue the newest session of this directory. |
| `venom -r`, `venom --resume` | Pick a saved session to resume. |
| `venom --session <path\|id>` | Open one by file, id or id prefix. |
| `venom --fork <path\|id>` | Fork a saved session into a new one. |
| `/resume`, `/new`, `/tree`, `/fork` | The same inside a session. |
| `venom resume [task\|latest]` | Continue an interrupted task: a crash, a usage limit, a reboot, a dropped network. |
| `venom resume --list [--all]` | The interrupted tasks of this directory (`--all`: every directory). |

A task is a plain session (reopened with a note of what was in flight), a plan-execute run (it continues at its first unfinished step) or a scheduled run. One that stopped on a provider usage limit waits for the reset first. When you start a bare `venom` in a directory with an interrupted task, it asks once whether to resume it. Checkpoints are written to `~/.venom/tasks/`; venom.yaml `resume.checkpoints: false` turns them off, `resume.prompt: false` turns off the question.

## Summaries and search {#search}

When a session ends (or on `/summary`, or when it is shared) venom writes a short summary: the goal, how it ended, decisions, files touched and cost.

| Command | What it does |
|---|---|
| `venom sessions search [words] [--outcome done\|partial\|failed\|abandoned] [--repo <part>] [--since <n>d] [--min-cost <usd>] [--limit <n>] [--json]` | Sessions whose summary contains every word (path parts count). |
| `venom sessions list` | The newest summaries. |
| `venom sessions show <id\|latest> [--json]` | One summary. |

Summaries stay on this machine unless you are signed in to Venom Cloud and your organisation turned session summaries on; venom asks before the first upload. `VENOM_SESSION_SUMMARIES=off` stops summaries altogether. Outcome reports (counts only, no text) go to the Cloud on the same terms; `VENOM_SESSION_OUTCOMES=off` stops them.

## Replay {#replay}

```bash
venom session replay latest
```

`venom session replay <id|latest|file> [--turn <n>] [--plain] [--json] [--raw]` steps through a session turn by turn: each turn's model (requested and served), tokens, cost, latency, errors and tool calls, with subagent turns nested under the call that ran them. The file may be a session `.jsonl`, a `venom export --format jsonl` file, a JSON trace or a share body. Keys: `j`/`k` or arrows step, space plays, `+`/`-` change the speed, `$` jumps to the costliest turn, `e`/`E` to the next and previous error, `q` quits. `--plain` prints one line per turn (the default without a terminal).

To re-run a session's prompts on another model and compare, use `venom replay` (the [automation section](/docs/automation.md) of these docs).

## Export {#export}

`venom export <session-id|latest> [--format html|md|jsonl|otlp-json] [--out <path>|-] [--raw]` writes a saved session's full trace: your messages, thinking, every tool call with its input and output, permission decisions, subagent transcripts and the per-call meter.

| Option | Default | What it does |
|---|---|---|
| `--format` | `html` | `html` (one self-contained file), `md`, `jsonl` or `otlp-json` (OpenTelemetry spans). |
| `--out <path>` | `./venom-trace-<id>-<time>.<ext>` | Where to write; `-` writes to stdout. |
| `--raw` | off | Don't scrub secrets. |
| `--json` | off | Print `{ok, session, format, items, scrubbed, path}`. |

A session id may be a prefix; `latest` is the newest session of this directory (else anywhere). Secrets are scrubbed unless `--raw`. With `VENOM_TRACE_PROVIDER_STREAM=1` set while the session ran, `jsonl` also carries the raw provider stream events. `/export` in the TUI does the same for the session you are in.

## Share and redacted copies {#share}

| Command | What it does |
|---|---|
| `venom session export <id\|latest> [--out <path>\|-] [--redact <term>]… [--no-images]` | One self-contained HTML viewer that opens offline. |
| `venom session share <id\|latest> [--title <text>] [--redact <term>]… [--no-images] [--yes]` | Upload it to Venom Cloud, visible to your organisation (`venom cloud login` first). Sharing again replaces the share. |
| `venom session unshare <ss_id>` | Delete a share. |

Both redact first: your `--redact` terms, environment values, secret-named assignments, API keys and tokens, and your home directory. They print what was replaced with masked samples, and `share` asks before uploading unless `--yes` (without a terminal it refuses instead). Images are kept unless `--no-images`; `share` drops the largest first when the upload would pass the Cloud's 4 MB limit. `/share` in the TUI shares the session you are in; `/share live` lets teammates watch it as it runs.

## Attach to a running session {#attach}

`venom attach <session-id|prefix> [--url http://127.0.0.1:8790] [--json]` joins a session running in `venom serve`: it prints the end of the transcript, then streams what the agent does. The token comes from `VENOM_SERVER_TOKEN`. What you type:

| Input | What it does |
|---|---|
| text | Steer the agent while it runs, or start a prompt. |
| `/follow <text>` | Queue a follow-up for after the run. |
| `/abort` | Stop the current run. |
| `/approve`, `/deny` | Answer the oldest pending approval. |
| `/leave` (or `ctrl+d`, or `ctrl+c` once) | Detach; the session keeps running. |

`--json` prints one JSON event per line instead of text. Not to be confused with `ctrl+g x`, which clears the files attached to the prompt you are writing.

## Find the sessions that went wrong {#triage}

```bash
venom triage --since 7d
```

`venom triage` ranks saved sessions by how likely they went wrong: task not completed, user frustration, a request you had to repeat, a missing tool or permission, a loop of the same failing action, success claimed that the transcript doesn't show. Each session gets the turn to look at first. Nothing in the sessions changes.

| Option | Default | What it does |
|---|---|---|
| `--since <t>` | `7d` | Sessions modified since: `7d`, `12h`, `2w` or a date. |
| `--until <date>` | none | Sessions started before. |
| `--session <ids>` | none | These sessions (ids or prefixes of 6+ characters), any directory. |
| `--all` | off | Every directory (default: sessions started here). |
| `--cwd <dir>` | here | Sessions started in this directory. |
| `--limit <n>` | `50` | Judge at most this many, newest first. |
| `--max-usd <usd>` | `0.25` | Stop starting requests past this spend (`0`: no cap). |
| `--decider <d>` | `auto` | `auto` (the decision model, then the fast model), `decide` or `llm`. |
| `--model <id>` | `VENOM_DECISION_MODEL`, else `venom-decide` | The decision model. |
| `--fast-model <id>` | `venom-fast` | The chat model the `llm` decider asks. |
| `--concurrency <n>` | `4` | Sessions judged at once. |
| `--json` | off | The `venom.triage/v1` report. |

What leaves the machine: each session's compact state (your messages, tool names with a one-line summary, errors, denials, the final reply; secrets scrubbed, home shown as `~`) goes to your endpoint at `VENOM_BASE_URL`.

## Fine-tuning data {#export-traces}

```bash
venom export-traces --out ./traces --since 30d --min-quality 0.75
```

`venom export-traces --out <dir> [--since 7d|<date>] [--min-quality 0.5]` writes the good sessions of the local store as chat-format JSONL for LoRA fine-tuning (axolotl, unsloth, llama-factory): `openai.jsonl` (OpenAI messages with `tool_calls`), `sharegpt.jsonl` (ShareGPT conversations) and `manifest.json` (what was kept, what was dropped and why). Good means no error or abort, a finished run, no call you denied, no failing last test run and no rollback. The quality score starts at 0.5, adds 0.25 for a recorded passing test run and 0.25 times the share of tool calls that succeeded. Secrets are scrubbed and near-duplicates dropped. Nothing is uploaded.

## Troubleshooting {#troubleshooting}

| Message | Cause and fix |
|---|---|
| `ambiguous_session` | The id prefix matches several sessions: give more characters. |
| `session_not_found` | No session with that id here; `latest` looks in this directory first, then anywhere. |
| `not_configured` (share) | Not signed in to Venom Cloud: `venom cloud login`. |
| `too_large` (share) | Over 4 MB even without images: add `--no-images` or share a shorter session. |
| `venom attach` gets 401 | `VENOM_SERVER_TOKEN` doesn't match the token `venom serve` was started with. |
