# 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

```bash
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](/terminal/memory-and-bridge) 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

```bash
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

```bash
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](/terminal/permissions-and-privacy) for what does and doesn't leave it.

## Related

[Configuration](/terminal/configuration) covers the compaction and snapshot settings, [Memory & context bridge](/terminal/memory-and-bridge) covers durable memory, and [Sessions](/editor/sessions) covers the editor's model.