Resume

aichat resume lets you continue sessions with lineage-based chaining for better control than compaction alone. Compaction preserves full history on disk but reduces the active API context to a lossy summary. With aichat resume, you get a fresh session that links back to every ancestor with explicit lineage pointers and tools to recover any detail on demand.

Installation

Part of the claude-code-tools package. See Quick Start for installation.

Demo

Resume strategies

When you resume a session, you choose one of these strategies:

Strategy	What it does	When to use
Resume as-is	Open the session directly with claude --resume	Still have context headroom
Clone	Copy session file, resume the clone	Want a safety copy first
Trim	Truncate bloated tool outputs and early messages	Quick fix, frees 30-50%
Smart trim	AI decides what is safe to cut	Surgical precision needed
Rollover	Fresh session with lineage pointers	Clean slate, full history preserved

Rollover is the most frequently used strategy. See Rollover Details for a deep dive on how it works.

Three ways to access the resume options

In-Session Trigger

While inside a Claude Code session, when you are close to filling up context, type:

>resume

(Or >continue, >handoff — the > prefix is required.)

This triggers a UserPromptSubmit hook that blocks handling by Claude Code (no further tokens consumed), copies the current session ID to your clipboard, and shows instructions to quit and run aichat resume <paste>.

The same hook also provides a >trim trigger that trims the current session file in place — no need to quit and resume.

Requires the aichat plugin.

Search TUI

Run aichat search, select a session, then choose a resume action from the menu:

aichat search "my topic"

See the Search page for details.

Direct CLI

Use the resume subcommand directly:

# Resume the latest session for this project
aichat resume

# Resume a specific session by ID
aichat resume abc123-def456

Trimming in place with >trim

The Trim strategy above spins up a new trimmed session. To slim down the session you are already in — keeping its same ID — type >trim.

The typical workflow

Two safe steps in the session, then a resume:

>trim              # preview savings — changes nothing
>trim yes          # apply — rewrites this session's file in place

# then, to actually reclaim the space:
quit (Ctrl+D twice)  →  claude -r <id>   (or  aichat resume)

That is the whole loop: preview → apply → quit → resume.

Trimming never shrinks the live context

Claude Code loads the transcript into context once, at session start, and never re-reads the file mid-session. So a trim only takes effect on the next resume — at any utilization level. Your only in-session levers are /compact (a lossy summary) or /clear (drops everything); >trim + resume is the lossless equivalent.

So run >trim before you hit the wall. Once Claude Code shows Context limit reached · /compact or /clear to continue, the live context is what is full, so >trim typed there cannot rescue it — quit and resume (optionally aichat trim-in-place <id> from a shell first) to come back lean.

Options (in-session)

Arguments are shape-based and order-free — mix them in any order:

• >trim help — show usage; touches nothing
• -N / +N — assistant messages: keep the last N / trim the first N long ones
• a bare number — character threshold (default 500)
• comma-separated words — tool names to trim (default: all tools)

>trim -20            # keep last 20 long assistant messages
>trim 800            # only trim content longer than 800 chars
>trim bash,read      # only Bash/Read tool results
>trim -20 800 bash   # combine — any order works
>trim yes | cancel   # apply / abandon a pending preview

A pending preview expires after ~10 minutes. Applying keeps the same session ID and writes a timestamped backup (<id>.pre-trim-<ts>.jsonl.bak) next to the file, which the truncation placeholders reference.

When a trim times out

The hook gives the trim a time budget: 25 seconds, plus a second per megabyte of transcript, capped at 60. If that runs out, the trim is stopped and the message tells you the budget that expired, the transcript and its size, which aichat your PATH resolved to, a copy-pasteable command to reproduce it, and whatever the CLI printed before it stopped.

A preview that times out changes nothing. An apply that times out is different: the subprocess is killed outright, so the rewrite may or may not have landed. That message says the outcome is unknown and points you at the timestamped .pre-trim-<ts>.jsonl.bak backup — check it before retrying.

Set AICHAT_TRIM_TIMEOUT (seconds, hard-capped at 75) before starting Claude to widen the budget:

AICHAT_TRIM_TIMEOUT=70 claude

The cap exists so the trim can never outlive the hook itself — otherwise Claude Code would kill the hook first and you would get no explanation at all.

Same engine on the command line

>trim shells out to aichat trim-in-place, which you can run directly on any Claude session (or from scripts):

aichat trim-in-place <id> --dry-run    # preview tokens saved
aichat trim-in-place <id>              # trim, keep same ID
aichat trim-in-place <id> -a -20       # keep last 20 asst msgs
aichat trim-in-place <id> -a 10        # trim first 10 asst msgs
aichat trim-in-place <id> -l 800       # char threshold 800
aichat trim-in-place <id> -t bash,read # only Bash/Read results
aichat trim-in-place <id> --json       # machine-readable result

Flags: -l/--len threshold (default 500), -a/--trim-assistant (positive N trims first N, negative N keeps last N), -t/--tools (comma-separated), -n/--dry-run, --json, --claude-home.

Requires the aichat CLI on PATH with the trim-in-place subcommand — install or update it with uv tool install --force claude-code-tools (see Plugins). Works on Claude sessions only (not Codex).

CLI usage

# Auto-find latest session for current project/branch
aichat resume

# Resume a specific session (opens resume menu)
aichat resume <session_id>

# A session name, or a partial id, works too
aichat resume session-finder
aichat resume a15f9ced

The resume menu presents the strategy options listed above. Pick one and the tool handles cloning, trimming, or rollover automatically.

The session argument accepts a name (set with /rename), a full or partial id, a rollout filename fragment, or a file path, across both agents — see Resolve. An ambiguous query lists the candidates instead of guessing.

Cloning follows the transcript you actually named. Give aichat clone a file path and it copies that file into the configured Claude project’s session directory under a fresh session id, even if the transcript lives outside the Claude home — it does not rebuild a path from the working directory the session happens to record.

Rollover options

The rollover subcommand gives direct access to rollover with more control:

# Interactive rollover (shows lineage, pick options)
aichat rollover

# Quick rollover -- lineage only, no summarization
aichat rollover abc123 --quick

# Rollover with custom context-extraction prompt
aichat rollover abc123 -p "Focus on the auth changes"

Tip

The --quick flag skips the context-extraction step so the new session starts immediately. You can then instruct the agent to pull specific context from the lineage as needed.

Related commands

Command	Description
aichat lineage [session]	Show the parent lineage chain
aichat trim [session]	Trim session (interactive or direct)
aichat trim-in-place <session>	Trim in place, keeping the same session ID
aichat rollover [session]	Rollover to fresh session
aichat clone [session]	Clone a session file

Why not just compact and read the session file?

Since compaction preserves full history on disk, you might wonder: why not just stay in the same session and read the session file when you need old details? A few reasons:

• Unbounded file growth — Compaction only adds records (a boundary marker + summary). It never deletes. After several compactions the session file grows large, making it progressively harder to parse and recover specific details.
• Summary-of-summary degradation — Each compaction summarizes the previous summary plus new work. This compounds lossy compression — details degrade with every cycle.
• No built-in recovery path — After compaction the agent only has the summary in its active context. It has no instructions, lineage pointers, or tools to go read the session file for missing details.
• Curated context — Rollover lets you (or an agent) inject a structured summary into a fresh session, often higher quality than what automatic compaction produces. Each session’s file stays bounded and frozen, making it a stable artifact for future reference.

How lineage works

Every resumed session carries metadata linking it back to its parent:

{
  "continue_metadata": {
    "parent_session_file": "/path/to/parent.jsonl",
    "parent_session_id": "abc123-...",
    "continued_at": "2025-12-19T..."
  }
}

This creates a linked chain that the agent can traverse to recover any prior context. For the full technical details, see Rollover Details.