Sessions

A session is a saved conversation. Raw stores the history and the context that the model uses. The terminal, the dashboard and ACP clients all read and write the same sessions, so you can start a task in one and continue it in another.

Resume a session

Command	Result
raw --continue "task"	Resumes the most recent unexpired session for the current workspace.
raw --resume ID "task"	Resumes one session in the working directory it was saved with, and prints that directory.
raw sessions	Lists sessions in the current workspace, with a cursor for the next page.
raw sessions --all	Lists sessions across all workspaces.
raw sessions show ID	Prints the newest 20 visible items of a session, formatted with your current display settings.
raw sessions show ID --before CURSOR	Prints an older page.

Running a task with --continue or --resume loads the current agent, tools, skills, MCP servers, limits and prompt from your config. The session keeps its ID and its committed history.

When a session is resumed with --config or --agent, the explicit value replaces the saved one for that run, and Raw saves the new selection for the next resume. A session whose saved working directory has been removed, or whose selected config file is missing, reports an error. Pass an explicit --config to recover a session whose original config file no longer exists.

With a task, stdout contains only the new answer. Viewing a session with raw sessions show needs no model credential and starts no tools.

Start a new session

Each one-shot task starts a new session unless you pass --continue or --resume. In the REPL, /clear closes the current session and starts a new saved one. The old history remains available.

Delete a session

raw sessions delete ID

This permanently removes one session that is not currently active. Raw does not export or archive it first. To see storage use, run raw sessions stats. It reports the database, write-ahead log and payload sizes, plus the largest sessions.

Where sessions are stored

Sessions are stored in a database that is private to your operating system account:

• $XDG_STATE_HOME/raw/sessions.sqlite, or
• ~/.local/state/raw/sessions.sqlite when XDG_STATE_HOME is not set.

Large payloads, such as big tool outputs, are kept as checksum-verified files beside the database in the same state directory.

If Raw finds an older database format that it cannot read, it leaves that file untouched. New sessions are stored in a separate database under raw/stores/, inside the same state root. Raw does not migrate old sessions automatically. A session that exists only in the preserved file is unavailable until that file is handled separately.

Retention

By default, a session expires seven days after its last committed conversation activity. Reading history, listing sessions and viewing metrics do not extend the period.

To change the period, set sessions.retention_days to a positive integer in the canonical global config file, ~/.config/raw/config.json (or $XDG_CONFIG_HOME/raw/config.json):

{
  "sessions": { "retention_days": 14 }
}

An alternate file passed with --config cannot set this value. The retention policy applies to the shared session store, so Raw rejects a sessions block in an alternate config.

When a session expires:

1. It becomes unavailable immediately.
2. Raw permanently deletes its history, its active model context and its payload files during routine cleanup.

Cleanup runs after session commands, and a long-running ACP server checks while idle. A session with live background processes stays available while its owning host runs, even after the cutoff.

Expired sessions cannot be recovered

Cleanup is permanent. Raw does not export or pin sessions. If you need to keep history beyond the retention period, back up the entire state directory before the cutoff. Include both database files and the payload files beside them. Copy the whole raw state directory, not only sessions.sqlite.

Sessions and the dashboard

The dashboard creates and resumes the same sessions as the terminal. Closing a browser tab does not stop a run. If a session is busy in another process, the dashboard can still read it. It becomes runnable there after that process releases the session.

Tips

• Use raw --continue for a quick follow-up in the same project.
• Use raw sessions to find an older session by its ID. Copy the ID from the footer or the dashboard’s resume command.
• Keep a session’s workspace and config stable. A change to the agent, model or tools applies on the next resume, while the history stays the same.