Files
luxe/docs/guide/sessions.md
Evan Whittaker 09a7de2520 Initial public release
Luxe 0.1.0: a coding agent harness for the terminal. See README.md to get started and CHANGELOG.md for releases.
2026-10-17 12:08:30 -05:00

7.1 KiB

title, summary, order, group
title summary order group
Sessions and context Resume past sessions, see what fills the context window, and how Luxe keeps long sessions going. 8 Using Luxe

Sessions

Every conversation is saved as it goes, in .luxe/sessions/ inside the project. Quitting loses nothing.

To In Luxe From the command line
Pick up the last session Resume on the start screen luxe -c
Find an older one Type part of its title on the start screen, or open Sessions… (/sessions) luxe sessions list, then luxe --resume <id>
Return to the session that worked on a pull request type #146 in Sessions… luxe --from-pr 146
Start fresh /new, or type on the start screen and press enter luxe

Sessions…, with the selected session's conversation previewed

Sessions… searches session titles and what was said in them, with a preview of the one under the cursor. /sessions opens it from the start screen or from inside a session. However you resume a session, it runs in its own worktree when it has one, and keeps what you had typed and the mode, model and thinking level you chose. /new keeps the session you leave, so you can come back to it.

Cost

The dock's SESSION section shows context used, tokens and cost as you go. /cost shows the session's cost with the tokens behind it, how much of the input was read from the provider's cache, and, once more than one of them has spent something, the split between agent, review, compaction and cache warming. On a ChatGPT or Copilot plan, it shows what the usage would have cost at API prices, and what is left of the plan's allowance when the provider reports it. A model that charges more for a long prompt, as models.dev lists for some Claude and Gemini models, is priced at the higher rate for each request past the threshold. A price you set in models.json replaces the catalog's, tiers and all.

Keeping the cache warm

Anthropic keeps a cached prompt for five minutes after it was last read. A turn that waits longer than that, on a slow command, a permission prompt or a question, loses the cache, and the next request pays to write the whole conversation again: about $2 on a 400k-token Opus session. So while a turn runs, Luxe re-sends its last request with a one-token reply just before the five minutes are up. That costs a cache read, a tenth of the write it saves.

agent.cache_warming decides when:

Value Keeps the cache warm
streaming (default) While a turn is running
idle While a turn is running, and for up to 30 minutes after it
off Never

A refresh goes out only when it is expected to save at least $0.05, so a short conversation is never refreshed. Between turns Luxe cannot know you will reply, so idle refreshes only a large conversation. On real sessions it lost money overall, which is why it is not the default. Refreshes are never sent on a subscription plan, or for an Anthropic model using a fixed thinking budget, whose cache would change on replay. Their cost shows under cache warming in /cost.

The other answer to a long pause is supports_long_cache_retention, which asks Anthropic to keep the cache for an hour; see Custom providers. It costs more on every turn instead of on each pause.

The context window

/context shows what fills the context window, largest first:

 GPT-5.6 Sol   18.5k of 1.1M · 2% used

  conversation     9.6k   52%
      `read` crat…-tui/src/statusline.rs   9.2k
  tool schemas     4.5k   25%
  instructions     2.8k   15%
  harness          1.5k    8%
  free             1.0M
Row Is Shrink it with
conversation Messages, tool calls and results, reasoning, images /compact, /new
tool schemas The tools the agent can call tools.disabled; see Tools
instructions Your AGENTS.md files A shorter file; see Project context
skills The list of skills the agent can load Fewer, or shorter descriptions
harness Luxe's own instructions Nothing; this is fixed
appended One-time context added to a resumed session, such as what changed while you were away /new

The largest single items are named under a row, which is usually how you find a read or bash call that should have been narrower. The total is what the provider reported for the last request.

Compaction

When a conversation fills 90% of the usable window, Luxe summarizes it and carries on, keeping the most recent part word for word. The summary records the goal, constraints, progress, decisions, next steps and the files the session touched. You see a line like Compacted the conversation — 82k → 21k of context.

/compact summarizes now. Add what matters to steer the summary: /compact the API decisions. A conversation that already fits in what keep_recent keeps has nothing to summarize, and /compact says so.

Before summarizing, from 80% full, Luxe first replaces old tool output in the request with a short placeholder. The session file keeps everything; only what is sent changes.

To change when and how it happens:

{
  "compaction": {
    "auto": true,
    "at": 0.9,
    "keep_recent": 20000,
    "reserve": 20000,
    "prune": true,
    "summarizer": "anthropic/claude-haiku-4-5"
  }
}
Key Default Does
auto true Summarize automatically. Off leaves it to /compact and turns pruning off too; a request the provider refuses as too long is still summarized and sent again, once.
at 0.9 How full the usable window gets before summarizing. Pruning starts 0.1 earlier.
keep_recent 20000 Tokens of the newest conversation kept word for word
reserve 20000 Most tokens held back for the reply when judging how full the window is, or the model's output limit if that is smaller
prune true Replace old tool output before summarizing
summarizer the session's model The model that writes the summary, as provider/id, on a provider you have set up. A smaller, cheaper model is usually enough, and /cost prices its spend as it does any other model's.

This works in a project's .luxe/config.json too, and so does agent.cache_warming, which a project can turn down but not up. The compaction settings in /settings apply the next time Luxe starts.

Long command output

Build, test and lint output is trimmed before the agent sees it. Errors, warnings, failing tests, file:line locations and exit codes are always kept; progress bars, color codes and repeated lines are not. When output is trimmed, the untouched text is saved under .luxe/artifacts/ (each stream whole up to 8 MB, or its first and last 4 MB past that) and its path is included, so the agent can read it if it needs to. Set LUXE_COMPRESS=0 to turn this off; output past the size limit is still cut and saved.

Searches and listings (grep, glob, git log) are capped the same way, with a note saying how many more results there are.