Sessions & context

A session is one conversation and everything it did — messages, tool calls, file changes. Sessions are saved locally as you work, so closing the terminal doesn’t lose anything.

Starting and resuming

Command	What it does
/new	Start a fresh session. Alias: /clear.
/sessions	Switch to another session. Aliases: /resume, /continue.
v3code -c	Continue the most recent session for this project.
v3code --session <id>	Continue a specific session.
v3code --session <id> --fork	Branch off a session, leaving the original untouched.

Forking is the useful one when you want to try a different approach from a known-good point without losing the path you already have.

Managing them from the CLI

v3code session list            # every session, newest first
v3code session list -n 10      # just the last ten
v3code session delete <id>     # remove one

Sessions get a short title automatically, generated by the small_model you configured, so a list of past work is actually readable.

Undoing work

If the agent went the wrong way, you don’t have to repair the files by hand. V3Code takes a snapshot as it works, so a session can be rolled back to an earlier message — the files return to how they were at that point.

You can also undo the undo: reverting is itself reversible, restoring the state you had before you rolled back.

Note

Snapshots are what make this possible, and they’re controlled by the snapshot setting. With snapshots off, revert has nothing to restore from.

Tip

Revert covers files V3Code changed. It isn’t a replacement for committing — commit at a known-good point and you always have a floor to stand on.

When a conversation gets long

Every model has a context limit. Rather than failing at the edge, V3Code compacts: it summarizes the earlier part of the conversation and keeps going.

What survives compaction is tunable:

Setting	Default	Effect
compaction.auto	true	Compact automatically when the window fills.
compaction.tail_turns	2	How many recent user turns are kept word-for-word.
compaction.preserve_recent_tokens	—	A token ceiling on what’s preserved verbatim.
compaction.prune	false	Drop old tool outputs, which are usually the bulkiest part.
compaction.reserved	—	Buffer left free so compaction itself has room to run.

A dedicated internal compaction agent does this work, which is why it doesn’t disturb your current agent or model choice.

Note

Compaction condenses the conversation. Durable facts saved to memory are a separate store and aren’t affected — that’s the difference between what was said and what was learned.

You can also cap how much any single tool result contributes, with tool_output.max_lines and tool_output.max_bytes.

Exporting and importing

v3code export <sessionID>              # write the session as JSON
v3code export <sessionID> --redact     # redact sensitive transcript and file data
v3code import <file-or-url>            # bring a session in

Note

Use --redact before sharing an export. A raw export contains the full transcript and file contents, which can include secrets that were on screen.

Sharing

/share creates a link to a session. It’s manual by default — nothing is published unless you ask. The share setting accepts manual, auto, or disabled, and disabled turns the feature off entirely for a project.

Usage and cost

v3code stats                # all-time tokens and cost
v3code stats --days 7       # the last week
v3code stats --models       # break it down by model

Where sessions live

Session data is written under ~/.local/share/v3code/, and v3code debug paths prints the exact locations. It stays on your machine — see Permissions & privacy for what does and doesn’t leave it.

Related

Configuration covers the compaction and snapshot settings, Memory & context bridge covers durable memory, and Sessions covers the editor’s model.