Undo file edits and rewind conversations

Conversation rewind and file restore are separate operations. Use /rewind to change what the model remembers, and git or explicitly enabled SDK file checkpoints to change what is on disk.

Edit an earlier promptCopy Anchor Link

Conversation rewind is available on both the Anthropic and OpenAI-compatible providers. It requires an interactive terminal and cannot run while a turn is in flight. Tool-result messages are not offered as user prompts. A prompt without text, such as an image-only turn, is not a rewind target.

Rewind is a conversation branch operation, not a transaction rollback. For example, if a discarded turn created a file, the model may no longer remember creating it, but the file remains. Tell the model about the current disk state before asking it to repeat the work.

Restore file checkpoints from the SDKCopy Anchor Link

File checkpointing is an opt-in AgentConfig capability, disabled by default. It is implemented for both providers. There is not currently a CLI checkpoint toggle or a /rewind files picker. Applications embedding afk enable it when they create a session.

Checkpoints save a file's state before the first supported write to that path in a turn. Supported tools are write_file, edit_file, and a non-dry-run patch_apply. Shell changes are not captured.

import { AgentSession } from 'agent-afk';

const session = new AgentSession({
  model: 'sonnet',
  enableFileCheckpointing: true,
});

const reply = await session.sendMessage(
  'Create a short draft in draft.txt using write_file.'
);
const checkpointId = reply.metadata?.userMessageId;

if (!checkpointId) throw new Error('No checkpoint target was returned.');

const preview = await session.rewindFiles(checkpointId, { dryRun: true });
if (!preview.canRewind) throw new Error(preview.error);
console.log(preview.filesChanged);

// Apply only after your application or user has approved the preview.
const restored = await session.rewindFiles(checkpointId);
if (!restored.canRewind) throw new Error(restored.error);
console.log(restored.filesChanged);

await session.close();

In a streaming application, the done event's metadata carries the same checkpoint ID. Stop the turn before restoring.

What a file restore doesCopy Anchor Link

For each tracked path, restore writes the saved bytes and mode, or deletes the file if it did not exist before that turn. Current write grants and protected-path rules are rechecked. A historical checkpoint does not grant new access.

A checkpoint covers paths touched in that turn, not a whole-workspace snapshot. It does not roll back unrelated files touched only by later turns. Restoring an old checkpoint can overwrite newer work at a tracked path, so inspect the diff and preview before applying it.

Restoration is per-file, not transactional. A failure can report some files already changed. Check canRewind, error, and filesChanged rather than assuming all-or-nothing success.

Checkpoint state lives under the configured AFK state directory at file-checkpoints/<sessionId>/. Saved content is deduplicated within the session. There is no automatic checkpoint retention or garbage collection policy yet. Checkpoints are not a security boundary against another process running as your user.

Keep git as the outer safety netCopy Anchor Link

Before a significant change, start from a known commit and use a feature branch or managed worktree. Git covers changes made through shell tools as well as typed file tools, provided you actually commit or otherwise preserve the work.

Inspect first:

git status --short
git diff
git diff --staged

Use the diff to distinguish the agent's changes from your own before restoring anything. Untracked files, ignored files, and external effects are not protected merely because you are in a git repository. Preserve anything irreplaceable before a destructive restore or worktree removal.

RelatedCopy Anchor Link