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.
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 organisationContinue 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.
Summaries and 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
venom session replay latestvenom 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 7dvenom 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.75venom 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. |