> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docwriter.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Persisted agent context, the transcript viewer, and starting fresh.

A **session** is the persisted state of one ongoing conversation with
the agent. It lives in `.docwriter/docwriter.db` and persists across
restarts. Reopening DocWriter resumes the same session — the agent
remembers prior turns, prior tool calls, and prior context within
limits.

You usually don't think about sessions. They're transparent. There
are two cases where they become visible.

## Starting a fresh session

Pass `--new-session` on the CLI:

```sh theme={null}
docwriter --new-session ~/path/to/workspace
```

DocWriter clears the persisted session ID at startup. The next agent
turn creates a new conversation. Files, tabs, rules, hooks, and
comments are not affected — only the agent's conversational memory.

Useful when:

* The agent has dug itself into a hole and you want a clean slate.
* You're switching context to a different writing project on the same
  workspace.
* You want the agent's behavior to be reproducible from a fresh
  state (e.g., for screenshots or testing).

You can also clear the session from inside DocWriter via the
**Settings** menu, **New session** item. Same effect, no restart.

## The transcript viewer

The history pane on the right shows the *current turn's* tool calls
live. To browse *prior turns* — every user message, every Claude
response, every tool call and result — open the **Transcript** button
at the top of the history pane.

The transcript viewer is a separate read-only window over the same
SQLite-backed session data. It has:

* Per-event filters (user messages, assistant text, tool calls, hook
  runs, errors).
* Free-text search across the whole transcript.
* Expandable tool-call entries showing the inputs (the agent's
  arguments) and outputs (what the tool returned).

The transcript is the system of record for what the agent did. If
something looks wrong in the history pane and you want to dig deeper,
the transcript is where you go.

## Sessions and hooks

Two hook events fire on session boundaries:

* **`SessionStart`** runs when a new agent session begins (first turn
  after `--new-session`, or when a fresh workspace is opened).
* **`SessionEnd`** runs when the session is cleared or the server
  shuts down cleanly.

Common uses:

```
Event:   SessionStart
Command: git pull --rebase --autostash || true
```

```
Event:   SessionEnd
Command: cp .docwriter/docwriter.db ~/Backups/docwriter-$(date +%F).db
```

See [Hook events](/automation/events) for the full event list and
[Hooks](/automation/hooks) for the hook configuration UI.

## What the agent remembers across sessions

Within a session, the agent has the full Claude Agent SDK conversation
context: prior user prompts, prior tool calls, prior reasoning.
Between sessions (after `--new-session`), all of that is gone.

What persists *regardless of session* — because they live in
DocWriter's own state, not the SDK's conversation:

* Your tab files (essay.md, paper/main.tex, etc.).
* Writing rules and writing references.
* Hooks.
* Open comment threads.
* Pending agent reviews.
* The recent-actions LRU for the [inline feedback
  popup](/agent/steering-the-agent#inline-feedback).
* The CRDT history (so undo/redo survives restarts).

A fresh session is just a fresh conversation. Your work doesn't move.