What would you like to be added?

Add support for a --to <user-message-index> flag to /rewind. When invoked as /rewind --to <N>, the command rewinds the conversation to the state just before the Nth user message (0-indexed) was sent — non-interactively, calling the existing rewindConversation() helper directly and returning a {type: 'message', ...} result instead of mounting the RewindViewer dialog. When invoked with no arguments, behavior is unchanged — the TUI opens as today.

This is a tiny change that lets an external process driving the CLI via stdin do what /rewind already does manually: trim the conversation while keeping the cached prefix intact. The helper, the guard checks, and the action's branching pattern all already exist — this just adds one more branch at the top.

Why is this needed?

Prompt cache preservation

The Gemini API charges roughly double for input above the 200K-token threshold on Pro-tier models.

For any long-running workflow that loads substantial context documents at session start, staying under 200K is the difference between sustainable cost and prohibitive cost. Session-start documents are typically the largest single chunk of context and are exactly what the prompt-caching layer is designed for .

/rewind is currently the only slash command that trims the conversation while keeping the cached prefix intact. The other options all destroy the front of the history outright:

• /clear removes all messages, including the loaded session-start documents. The documents themselves are gone — they have to be re-uploaded next cycle, cache cold.
• /compress rewrites the prefix into a summary, which discards the original messages entirely. Same effect: documents gone, cache invalidated.

So /rewind is the right operation for orchestrated cyclic workflows.

The only thing wrong with it is that it's only accessible through a TUI dialog (RewindViewer / RewindConfirmation in packages/cli/src/ui/components/), which an external process driving the CLI via stdin cannot navigate.

My orchestrated multi-cycle review workflow

I run an orchestrator (built around pexpect) that wraps the Gemini CLI for a multi-cycle review workflow:

1. Session start. I load context documents — frameworks, architecture references, decision logs, etc. These are large (often hundreds of KB), stay constant for the entire run, and are exactly what should sit in the prompt cache.
2. Cycle. I paste the current state of the dynamic documents (the artifact under review, plus any frequently-updated supporting docs), ask Gemini for a review, receive findings.
3. Apply fixes outside the Gemini session.
4. Trim the conversation back to the post-static-docs state so the next cycle starts from the same cached prefix and the conversation doesn't grow unbounded.
5. Loop. Paste the next iteration of the dynamic documents, ask for review, receive findings, trim, repeat.

I currently run this loop manually, using /rewind between cycles to trim. It keeps total per-cycle context just under the 200K-token threshold, the static prefix stays cached, and per-cycle cost stays flat — it works, but I can't leave the loop unattended.

I previously had this fully automated by having my orchestrator kill and respawn the Gemini CLI between cycles, but re-uploading the session-start documents (hundreds of KB) every time made it prohibitively expensive — the cache went cold on every cycle and per-cycle input cost climbed past the 200K threshold fast. So I switched back to running /rewind manually after every review. The TUI-only /rewind is the only existing operation that trims the conversation while preserving the cached prefix; what's missing is a way to invoke it from stdin. The proposal in the additional context section closes that gap.

Additional context

Proposed solution

Add a --to <user-message-index> flag to /rewind:

/rewind (no change — opens the RewindViewer TUI as today) /rewind --to Non-interactive: rewind to the Nth user message (0-indexed)

The user-message index matches the unit RewindViewer already uses to present rewind targets — only user messages are valid rewind points in the existing TUI, so the same indexing applies in the non-interactive mode. An orchestrator that loaded context documents at user message 0 will typically rewind with --to 1 on every cycle, dropping the most recent review exchange while preserving the cached prefix at message 0. We use a --to flag rather than a positional argument to keep orchestrator logs self-documenting and to leave the namespace open for future flags (like --revert-files).

Boundary semantics (--to N is exclusive)

--to <N> matches the existing ChatRecordingService.rewindTo() contract: user message N and everything after it are removed. The conversation is left in the state it was in just before user message N was sent. This is the same semantic the existing RewindViewer TUI uses today — selecting a message and confirming removes that message and everything from that point onward. The index is 0-indexed to match standard array offsets, since orchestration scripts work natively with this convention.

Concrete example. Suppose user message 0 contains your loaded session-start documents, and user message 1 contains a review request. To remove the review request (and the assistant's response to it) while preserving the loaded documents, run:

/rewind --to 1

This removes user message 1 and everything after, leaving the conversation at user message 0 + its assistant response — exactly the cached prefix the orchestrator wants to return to before pasting the next cycle's dynamic documents.

The exclusive semantic comes directly from the existing rewindTo() implementation in packages/core/src/services/chatRecordingService.ts; the non-interactive branch reuses it without modification, so the contract is automatically consistent with /rewind's TUI behavior. The non-interactive mode defaults to history-only — disk-side file revert (RewindOutcome.RewindAndRevert / RevertOnly) remains TUI-only, since it requires interactive confirmation. If non-interactive file revert becomes useful later, it can be added as a separate flag (e.g., --revert-files) in a follow-up.

Implementation pseudocode

The change slots cleanly into the top of rewindCommand.action in packages/cli/src/ui/commands/rewindCommand.tsx, reusing the existing rewindConversation helper before the RewindViewer dialog is ever mounted. No new files or command registrations are needed. Estimated diff: ~15–25 lines plus a unit test in the existing rewindCommand.test.tsx.

// Inside rewindCommand.action, after the existing guard checks:

const argTrimmed = args?.trim() ?? '';
if (argTrimmed) {
  // Match `--to <N>` or `--to=<N>`. Captures negative integers so we
  // can return a clear error instead of silently falling through to
  // the TUI on malformed input.
  const toMatch = argTrimmed.match(/^--to(?:\s+|=)(-?\d+)$/);
  if (!toMatch) {
    return { type: 'message', messageType: 'error',
             content: `Unrecognized arguments. Usage: /rewind --to <user-message-index>` };
  }

  const index = parseInt(toMatch[1], 10);

  const userMessages = conversation.messages.filter(m => m.role === 'user');
  if (isNaN(index) || index < 0 || index >= userMessages.length) {
    return { type: 'message', messageType: 'error',
             content: `Invalid index. --to requires a valid user message index (0 to ${Math.max(0, userMessages.length - 1)}).` };
  }

  // rewindTo is exclusive — user message at `index` is removed along
  // with everything after it.
  await rewindConversation(context, client, recordingService, userMessages[index].id, '');
  return { type: 'message', messageType: 'info',
           content: `Rewound to before user message ${index}.` };
}

// Existing path: no args → return the TUI
return { type: 'custom_dialog', component: <RewindViewer ... /> };

This is a strictly additive extension. It does not alter existing interactive /rewind behavior, the SlashCommand interface, or perform non-interactive disk side-effects (file reversion remains TUI-only).

Related issues

• #21891 — Stale Output Elision (History Pruning) (open) — proposes automatic heuristic-based pruning. Complementary, not duplicative. The proposal here is the deterministic, user-driven primitive that automation could be built on top of.
• #16955 — [Context Mgmt] Rolling Tool Output Pruning (closed) — proposed an automatic rolling window. Different problem (heuristic vs explicit, stale-output detection vs deterministic rewind point).

This proposal is the non-interactive equivalent of an operation /rewind already performs flawlessly through its TUI. It's the same relationship sed has to a text editor — same domain, different access pattern, both needed for different kinds of users.

Willing to PR

Happy to submit a pull request. The change is small, strictly additive, and uses the existing helpers and patterns.