Skip to content
Docs menu

Sessions, resume and export

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.

View .md

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.

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

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.

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

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 of these docs).

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

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

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

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

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

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.