docs

Sessions

Every conversation journals incrementally to an append-only JSONL file. A crash or Ctrl+C loses at most the in-flight turn.

Where sessions live

  • $XDG_DATA_HOME/dex/sessions (or ~/.local/share/dex/sessions).
  • Organized in subdirectories by a slug of the current working directory.
  • New sessions are named <workspace>-<7 chars> (workspace directory plus a k8s-style suffix, e.g. dex-k3m9x2q); override with --name or /name.

Journal format

Each file starts with a session header line followed by message entries and optional session_info (rename) entries. Entries are appended after every turn; turn_start/turn_complete/turn_failed markers make resumption exact. fsync happens only on turn_*/effect_* events by default — set DEX_DURABLE=1 for per-line durability.

Resume

  • Starting dex in a directory creates a fresh session; --session <path> continues a saved one.
  • Quitting the TUI prints the exact resume command for that session.
  • /resume [index|path] lists sessions or resumes one; session state re-applies the exact provider/model.
  • --reattach <id> attaches to a session a daemon still holds and replays its event journal — see client–daemon mode.
  • --no-session disables persistence for a run.

Context compaction

When a request would exceed the model's context window (context_window − reserve, reserve defaults to 16384 tokens), older turns are summarized deterministically — no LLM call — while the 20000 most recent tokens are kept (DEX_KEEP_RECENT_TOKENS). Set DEX_COMPACTION=llm for model-summarized compaction, or DEX_COMPACTION=jev for verbatim tool-output pruning — see experiments.

Steering & follow-ups

While dex is working, the input remains available. Submitted steering and follow-up messages stay visible in a queue directly above the input box until the worker accepts them. Steering is delivered before the next model call; follow-ups wait until the current task has finished. The queue is kept separate from the transcript so pending messages do not scroll away. Alt+Up recalls queued steers (newest first), then follow-ups, back into the composer for editing.

Undo & audit

  • /undo reverses the last recorded file change.
  • /session shows the current session id, path, and turn count.
  • Audit to audit.jsonl is off by default (DEX_AUDIT=1 to enable) — the session journal already records everything.