Rewind de alterações de arquivo com checkpointing

Rastreie alterações de arquivo durante sessões de agente e restaure arquivos para qualquer estado anterior

O checkpointing de arquivo rastreia modificações de arquivo feitas através das ferramentas Write, Edit e NotebookEdit durante uma sessão de agente, permitindo que você reverta arquivos para qualquer estado anterior. Quer experimentar? Vá para o exemplo interativo.

Com checkpointing, você pode:

Desfazer alterações indesejadas restaurando arquivos para um estado conhecido e bom
Explorar alternativas restaurando para um checkpoint e tentando uma abordagem diferente
Recuperar de erros quando o agente faz modificações incorretas

Como o checkpointing funciona

Quando você ativa o checkpointing de arquivo, o SDK cria backups de arquivos antes de modificá-los através das ferramentas Write, Edit ou NotebookEdit. As mensagens do usuário no fluxo de resposta incluem um UUID de checkpoint que você pode usar como ponto de restauração.

Quando você reverte para um checkpoint, Claude Code deleta os arquivos que criou e restaura os arquivos que modificou para seu conteúdo naquele ponto. Claude Code ignora um caminho rastreado que é um symlink, hard link ou outro arquivo não-regular. Ele também ignora um arquivo rastreado cujo diretório pai não resolve mais para sua localização no momento do checkpoint, ou cujo backup ele não consegue ler com segurança. RewindFilesResult conta cada caminho ignorado em seu campo skippedLinks. Ignorar requer Claude Code v2.1.216 ou posterior; antes de v2.1.216, uma reversão escrevia e deletava através de links em caminhos rastreados.

Implementar checkpointing

Para usar checkpointing de arquivo, ative-o em suas opções, capture UUIDs de checkpoint do fluxo de resposta e, em seguida, chame rewindFiles() (TypeScript) ou rewind_files() (Python) quando precisar restaurar.

O exemplo a seguir mostra o fluxo completo: ativar checkpointing, capturar o UUID de checkpoint e ID de sessão do fluxo de resposta e, em seguida, retomar a sessão mais tarde para reverter arquivos. Cada etapa é explicada em detalhes abaixo. Os exemplos nesta seção usam o prompt "Refactor the authentication module". Execute-os em um projeto que contenha um módulo de autenticação, ou altere o prompt para nomear arquivos que existem em seu projeto, para que você possa observar as alterações de arquivos e ver a reversão restaurá-los.

import asyncio
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
UserMessage,
ResultMessage,
)


async def main():
# Step 1: Enable checkpointing
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",  # Auto-accept file edits without prompting
extra_args={
"replay-user-messages": None
},  # Required to receive checkpoint UUIDs in the response stream
)

checkpoint_id = None
session_id = None

# Run the query and capture checkpoint UUID and session ID
async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

# Step 2: Capture checkpoint UUID from the first user message
async for message in client.receive_response():
if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
checkpoint_id = message.uuid
if isinstance(message, ResultMessage) and not session_id:
session_id = message.session_id

# Step 3: Later, rewind by resuming the session with an empty prompt
if checkpoint_id and session_id:
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)
break
print(f"Rewound to checkpoint: {checkpoint_id}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
// Step 1: Enable checkpointing
const opts = {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const, // Auto-accept file edits without prompting
extraArgs: { "replay-user-messages": null } // Required to receive checkpoint UUIDs in the response stream
};

const response = query({
prompt: "Refactor the authentication module",
options: opts
});

let checkpointId: string | undefined;
let sessionId: string | undefined;

// Step 2: Capture checkpoint UUID from the first user message
try {
for await (const message of response) {
if (message.type === "user" && message.uuid && !checkpointId) {
checkpointId = message.uuid;
}
if ("session_id" in message && !sessionId) {
sessionId = message.session_id;
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, sessionId and checkpointId were already
// captured by the loop above; connection or process failures yield no
// result message.
console.error(`Session ended with an error: ${error}`);
}

// Step 3: Later, rewind by resuming the session with an empty prompt
if (checkpointId && sessionId) {
const rewindQuery = query({
prompt: "", // Empty prompt to open the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(checkpointId);
break;
}
console.log(`Rewound to checkpoint: ${checkpointId}`);
}
}

main();

Ativar checkpointing

Configure suas opções de SDK para ativar checkpointing e receber UUIDs de checkpoint:

Opção	Python	TypeScript	Descrição
Ativar checkpointing	`enable_file_checkpointing=True`	`enableFileCheckpointing: true`	Rastreia alterações de arquivo para reversão
Receber UUIDs de checkpoint	`extra_args={"replay-user-messages": None}`	`extraArgs: { 'replay-user-messages': null }`	Necessário para obter UUIDs de mensagem do usuário no fluxo

options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

const response = query({
prompt: "Refactor the authentication module",
options: {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
}
});

Capturar UUID de checkpoint e ID de sessão

Com a opção replay-user-messages definida (mostrada acima), cada mensagem do usuário no fluxo de resposta tem um UUID que serve como um checkpoint.

Para a maioria dos casos de uso, capture o UUID da primeira mensagem do usuário (message.uuid); reverter para ele restaura todos os arquivos para seu estado original. Para armazenar múltiplos checkpoints e reverter para estados intermediários, veja Múltiplos pontos de restauração.

Capturar o ID de sessão (message.session_id) é opcional; você só precisa dele se quiser reverter mais tarde, após o fluxo ser concluído. Se você estiver chamando rewindFiles() imediatamente enquanto ainda processa mensagens (como o exemplo em Checkpoint antes de operações arriscadas faz), você pode pular a captura do ID de sessão.

checkpoint_id = None
session_id = None

async for message in client.receive_response():
# Capture the first user message UUID as the checkpoint
if isinstance(message, UserMessage) and message.uuid and checkpoint_id is None:
checkpoint_id = message.uuid
# Capture session ID from the result message
if isinstance(message, ResultMessage):
session_id = message.session_id

let checkpointId: string | undefined;
let sessionId: string | undefined;

for await (const message of response) {
// Capture the first user message UUID as the checkpoint
if (message.type === "user" && message.uuid && !checkpointId) {
checkpointId = message.uuid;
}
// Capture session ID from any message that has it
if ("session_id" in message) {
sessionId = message.session_id;
}
}

Reverter arquivos

Para reverter após o fluxo ser concluído, retome a sessão com um prompt vazio e chame rewind_files() (Python) ou rewindFiles() (TypeScript) com seu UUID de checkpoint. Você também pode reverter durante o fluxo; veja Checkpoint antes de operações arriscadas para esse padrão.

async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt to open the connection
async for message in client.receive_response():
if checkpoint_id:
await client.rewind_files(checkpoint_id)
break

const rewindQuery = query({
prompt: "", // Empty prompt to open the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
if (checkpointId) {
await rewindQuery.rewindFiles(checkpointId);
}
break;
}

Se você capturar o ID de sessão e o ID de checkpoint, você também pode reverter a partir da CLI. Este comando requer o executável claude, que vem de instalar Claude Code e não é instalado pelo pacote SDK. O SDK ativa checkpointing para você, mas quando você executa claude -p diretamente, você deve definir a variável de ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING:

CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

O sinalizador --rewind-files não aparece na saída de claude --help, mas a CLI o aceita conforme mostrado. Quando a reversão é bem-sucedida, o comando imprime Files rewound to state at message <checkpoint-uuid> e sai sem enviar um prompt.

Padrões comuns

Esses padrões mostram diferentes maneiras de capturar e usar UUIDs de checkpoint dependendo do seu caso de uso.

Checkpoint antes de operações arriscadas

Este padrão mantém apenas o UUID de checkpoint mais recente, atualizando-o antes de cada turno do agente. Se algo der errado durante o processamento, você pode reverter imediatamente para o último estado seguro e sair do loop.

Antes de executar este exemplo, substitua your_revert_condition (Python) ou yourRevertCondition (TypeScript) pela sua própria verificação, como detecção de erro ou falha de validação; o espaço reservado não está definido no exemplo.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage


async def main():
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

safe_checkpoint = None

async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

async for message in client.receive_response():
# Update checkpoint before each agent turn starts
# This overwrites the previous checkpoint. Only keep the latest
if isinstance(message, UserMessage) and message.uuid:
safe_checkpoint = message.uuid

# Decide when to revert based on your own logic
# For example: error detection, validation failure, or user input
if your_revert_condition and safe_checkpoint:
await client.rewind_files(safe_checkpoint)
# Exit the loop after rewinding, files are restored
break


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
const response = query({
prompt: "Refactor the authentication module",
options: {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
}
});

let safeCheckpoint: string | undefined;

for await (const message of response) {
// Update checkpoint before each agent turn starts
// This overwrites the previous checkpoint. Only keep the latest
if (message.type === "user" && message.uuid) {
safeCheckpoint = message.uuid;
}

// Decide when to revert based on your own logic
// For example: error detection, validation failure, or user input
if (yourRevertCondition && safeCheckpoint) {
await response.rewindFiles(safeCheckpoint);
// Exit the loop after rewinding, files are restored
break;
}
}
}

main();

Múltiplos pontos de restauração

Se Claude fizer alterações em múltiplos turnos, você pode querer reverter para um ponto específico em vez de voltar completamente. Por exemplo, se Claude refatorar um arquivo no turno um e adicionar testes no turno dois, você pode querer manter a refatoração mas desfazer os testes.

Este padrão armazena todos os UUIDs de checkpoint em um array com metadados. Após a sessão ser concluída, você pode reverter para qualquer checkpoint anterior:

import asyncio
from dataclasses import dataclass
from datetime import datetime
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
UserMessage,
ResultMessage,
)


# Store checkpoint metadata for better tracking
@dataclass
class Checkpoint:
id: str
description: str
timestamp: datetime


async def main():
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

checkpoints = []
session_id = None

async with ClaudeSDKClient(options) as client:
await client.query("Refactor the authentication module")

async for message in client.receive_response():
if isinstance(message, UserMessage) and message.uuid:
checkpoints.append(
Checkpoint(
id=message.uuid,
description=f"After turn {len(checkpoints) + 1}",
timestamp=datetime.now(),
)
)
if isinstance(message, ResultMessage) and not session_id:
session_id = message.session_id

# Later: rewind to any checkpoint by resuming the session
if checkpoints and session_id:
target = checkpoints[0]  # Pick any checkpoint
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt to open the connection
async for message in client.receive_response():
await client.rewind_files(target.id)
break
print(f"Rewound to: {target.description}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

// Store checkpoint metadata for better tracking
interface Checkpoint {
id: string;
description: string;
timestamp: Date;
}

async function main() {
const opts = {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
};

const response = query({
prompt: "Refactor the authentication module",
options: opts
});

const checkpoints: Checkpoint[] = [];
let sessionId: string | undefined;

try {
for await (const message of response) {
if (message.type === "user" && message.uuid) {
checkpoints.push({
id: message.uuid,
description: `After turn ${checkpoints.length + 1}`,
timestamp: new Date()
});
}
if ("session_id" in message && !sessionId) {
sessionId = message.session_id;
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, sessionId and the checkpoints array were
// already populated by the loop above; connection or process failures
// yield no result message.
console.error(`Session ended with an error: ${error}`);
}

// Later: rewind to any checkpoint by resuming the session
if (checkpoints.length > 0 && sessionId) {
const target = checkpoints[0]; // Pick any checkpoint
const rewindQuery = query({
prompt: "", // Empty prompt to open the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(target.id);
break;
}
console.log(`Rewound to: ${target.description}`);
}
}

main();

Experimente

Este exemplo completo cria um pequeno arquivo utilitário, faz o agente adicionar comentários de documentação, mostra as alterações e pergunta se você quer reverter.

Antes de começar, certifique-se de que você tem o Claude Agent SDK instalado.

Criar um arquivo de teste

Crie um novo arquivo chamado utils.py (Python) ou utils.ts (TypeScript) e cole o seguinte código:

def add(a, b):
return a + b


def subtract(a, b):
return a - b


def multiply(a, b):
return a * b


def divide(a, b):
if b == 0:
raise ValueError("Cannot divide by zero")
return a / b

export function add(a: number, b: number): number {
return a + b;
}

export function subtract(a: number, b: number): number {
return a - b;
}

export function multiply(a: number, b: number): number {
return a * b;
}

export function divide(a: number, b: number): number {
if (b === 0) {
throw new Error("Cannot divide by zero");
}
return a / b;
}

Executar o exemplo interativo

Crie um novo arquivo chamado try_checkpointing.py (Python) ou try_checkpointing.ts (TypeScript) no mesmo diretório que seu arquivo utilitário e cole o seguinte código.

Este script pede ao Claude para adicionar comentários de documentação ao seu arquivo utilitário e, em seguida, oferece a opção de reverter e restaurar o original.

import asyncio
from claude_agent_sdk import (
ClaudeSDKClient,
ClaudeAgentOptions,
UserMessage,
ResultMessage,
)


async def main():
# Configure the SDK with checkpointing enabled
# - enable_file_checkpointing: Track file changes for rewinding
# - permission_mode: Auto-accept file edits without prompting
# - extra_args: Required to receive user message UUIDs in the stream
options = ClaudeAgentOptions(
enable_file_checkpointing=True,
permission_mode="acceptEdits",
extra_args={"replay-user-messages": None},
)

checkpoint_id = None  # Store the user message UUID for rewinding
session_id = None  # Store the session ID for resuming

print("Running agent to add doc comments to utils.py...\n")

# Run the agent and capture checkpoint data from the response stream
async with ClaudeSDKClient(options) as client:
await client.query("Add doc comments to utils.py")

async for message in client.receive_response():
# Capture the first user message UUID - this is our restore point
if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
checkpoint_id = message.uuid
# Capture the session ID so we can resume later
if isinstance(message, ResultMessage):
session_id = message.session_id

print("Done! Open utils.py to see the added doc comments.\n")

# Ask the user if they want to rewind the changes
if checkpoint_id and session_id:
response = input("Rewind to remove the doc comments? (y/n): ")

if response.lower() == "y":
# Resume the session with an empty prompt, then rewind
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")  # Empty prompt opens the connection
async for message in client.receive_response():
await client.rewind_files(checkpoint_id)  # Restore files
break

print(
"\n✓ File restored! Open utils.py to verify the doc comments are gone."
)
else:
print("\nKept the modified file.")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as readline from "readline";

async function main() {
// Configure the SDK with checkpointing enabled
// - enableFileCheckpointing: Track file changes for rewinding
// - permissionMode: Auto-accept file edits without prompting
// - extraArgs: Required to receive user message UUIDs in the stream
const opts = {
enableFileCheckpointing: true,
permissionMode: "acceptEdits" as const,
extraArgs: { "replay-user-messages": null }
};

let sessionId: string | undefined; // Store the session ID for resuming
let checkpointId: string | undefined; // Store the user message UUID for rewinding

console.log("Running agent to add doc comments to utils.ts...\n");

// Run the agent and capture checkpoint data from the response stream
const response = query({
prompt: "Add doc comments to utils.ts",
options: opts
});

try {
for await (const message of response) {
// Capture the first user message UUID - this is our restore point
if (message.type === "user" && message.uuid && !checkpointId) {
checkpointId = message.uuid;
}
// Capture the session ID so we can resume later
if ("session_id" in message) {
sessionId = message.session_id;
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, checkpointId and sessionId were already
// captured by the loop above; connection or process failures yield no
// result message.
console.error(`Session ended with an error: ${error}`);
}

console.log("Done! Open utils.ts to see the added doc comments.\n");

// Ask the user if they want to rewind the changes
if (checkpointId && sessionId) {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});

const answer = await new Promise<string>((resolve) => {
rl.question("Rewind to remove the doc comments? (y/n): ", resolve);
});
rl.close();

if (answer.toLowerCase() === "y") {
// Resume the session with an empty prompt, then rewind
const rewindQuery = query({
prompt: "", // Empty prompt opens the connection
options: { ...opts, resume: sessionId }
});

for await (const msg of rewindQuery) {
await rewindQuery.rewindFiles(checkpointId); // Restore files
break;
}

console.log("\n✓ File restored! Open utils.ts to verify the doc comments are gone.");
} else {
console.log("\nKept the modified file.");
}
}
}

main();

Executar o exemplo

Execute o script do mesmo diretório que seu arquivo utilitário.

python try_checkpointing.py

npx tsx try_checkpointing.ts

Você verá o agente adicionar comentários de documentação e, em seguida, um prompt perguntando se você quer reverter. Se você escolher sim, o arquivo é restaurado para seu estado original.

Limitações

O checkpointing de arquivo tem as seguintes limitações:

Limitação	Descrição
Apenas ferramentas Write/Edit/NotebookEdit	As alterações feitas através de comandos Bash não são rastreadas
Edições de subagent	Edições que um subagent aplica não são rastreadas ou restauradas, exceto uma skill com `context: fork` executando em primeiro plano; use git para reverter edições não rastreadas
Mesma sessão	Os checkpoints estão vinculados à sessão que os criou
Apenas conteúdo de arquivo	Criar, mover ou deletar diretórios não é desfeito pela reversão
Arquivos locais	Arquivos remotos ou de rede não são rastreados

Troubleshooting

Opções de checkpointing não reconhecidas

Se enableFileCheckpointing ou rewindFiles() não estiver disponível, você pode estar em uma versão mais antiga do SDK.

Solução: Atualize para a versão mais recente do SDK:

Python: pip install --upgrade claude-agent-sdk
TypeScript: npm install @anthropic-ai/claude-agent-sdk@latest

Mensagens do usuário não têm UUIDs

Se message.uuid for undefined ou estiver faltando, você não está recebendo UUIDs de checkpoint.

Causa: A opção replay-user-messages não está definida.

Solução: Adicione extra_args={"replay-user-messages": None} (Python) ou extraArgs: { 'replay-user-messages': null } (TypeScript) às suas opções.

Erro "No file checkpoint found for this message"

Este erro ocorre quando os dados de checkpoint não existem para o UUID de mensagem do usuário especificado.

Causas comuns:

O checkpointing de arquivo não foi ativado na sessão original (enable_file_checkpointing ou enableFileCheckpointing não foi definido como true)
A sessão não foi concluída adequadamente antes de tentar retomar e reverter

Solução: Certifique-se de que enable_file_checkpointing=True (Python) ou enableFileCheckpointing: true (TypeScript) foi definido na sessão original, depois use o padrão mostrado nos exemplos: capture o UUID da primeira mensagem do usuário, conclua a sessão completamente e, em seguida, retome com um prompt vazio e chame rewindFiles() uma vez.

Erro "File rewinding is not enabled"

Este erro ocorre quando você tenta um rewind não interativo sem checkpointing ativado: executar claude -p simples com --rewind-files, ou executar uma sessão SDK, incluindo uma retomada, cujas opções não ativam checkpointing. O SDK define a variável de ambiente CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING internamente apenas quando enable_file_checkpointing (Python) ou enableFileCheckpointing (TypeScript) está ativado na sessão que executa o rewind; a CLI simples nunca a define.

Solução: Para a CLI simples, defina a variável de ambiente ao executar o comando:

CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

Para o SDK, defina enable_file_checkpointing=True (Python) ou enableFileCheckpointing: true (TypeScript) na sessão retomada, como os exemplos nesta página fazem.

Erro "ProcessTransport is not ready for writing"

Este erro ocorre quando você chama rewindFiles() ou rewind_files() após ter terminado de iterar através da resposta. A conexão com o processo CLI fecha quando o loop é concluído.

Solução: Retome a sessão com um prompt vazio e, em seguida, chame rewind na nova query:

# Resume session with empty prompt, then rewind
async with ClaudeSDKClient(
ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
) as client:
await client.query("")
async for message in client.receive_response():
if checkpoint_id:
await client.rewind_files(checkpoint_id)
break

// Resume session with empty prompt, then rewind
const rewindQuery = query({
prompt: "",
options: { ...opts, resume: sessionId }
});

try {
for await (const msg of rewindQuery) {
if (checkpointId) {
await rewindQuery.rewindFiles(checkpointId);
}
break;
}
} catch (error) {
// An error here means the rewind didn't complete, for example the checkpoint
// wasn't found or the session couldn't be resumed.
console.error(`Rewind session ended with an error: ${error}`);
}

Próximos passos

Sessions: aprenda como retomar sessões, o que é necessário para reverter após o fluxo ser concluído. Cobre IDs de sessão, retomada de conversas e bifurcação de sessão.
Permissions: configure quais ferramentas Claude pode usar e como as modificações de arquivo são aprovadas. Útil se você quiser mais controle sobre quando as edições acontecem.
TypeScript SDK reference: referência completa da API incluindo todas as opções para query() e o método rewindFiles().
Python SDK reference: referência completa da API incluindo todas as opções para ClaudeAgentOptions e o método rewind_files().

agent-sdk/file-checkpointing.md +49 −33

15* **Recuperar de erros** quando o agente faz modificações incorretas15* **Recuperar de erros** quando o agente faz modificações incorretas

16 16

17<Warning>17<Warning>

18 Apenas as alterações feitas através das ferramentas Write, Edit e NotebookEdit são rastreadas. As alterações feitas através de comandos Bash (como `echo > file.txt` ou `sed -i`) não são capturadas pelo sistema de checkpoint.18 Apenas as alterações feitas através das ferramentas Write, Edit e NotebookEdit são rastreadas. As alterações feitas através de comandos Bash (como `echo > file.txt` ou `sed -i`) não são capturadas pelo sistema de checkpoint, e nem são as edições que um [subagente](/docs/pt/agent-sdk/subagents) aplica, exceto uma [skill com `context: fork`](/docs/pt/skills#run-skills-in-a-subagent) que é executada em primeiro plano.

19</Warning>19</Warning>

20 20

21<h2 id="how-checkpointing-works">21<h2 id="how-checkpointing-works">

24 24

25Quando você ativa o checkpointing de arquivo, o SDK cria backups de arquivos antes de modificá-los através das ferramentas Write, Edit ou NotebookEdit. As mensagens do usuário no fluxo de resposta incluem um UUID de checkpoint que você pode usar como ponto de restauração.25Quando você ativa o checkpointing de arquivo, o SDK cria backups de arquivos antes de modificá-los através das ferramentas Write, Edit ou NotebookEdit. As mensagens do usuário no fluxo de resposta incluem um UUID de checkpoint que você pode usar como ponto de restauração.

26 26

~~27O checkpoint funciona com essas ferramentas integradas que o agente usa para modificar arquivos:~~

~~29| Ferramenta | Descrição |~~

~~30| ------------ | -------------------------------------------------------------------------- |~~

~~31| Write | Cria um novo arquivo ou sobrescreve um arquivo existente com novo conteúdo |~~

~~32| Edit | Faz edições direcionadas em partes específicas de um arquivo existente |~~

~~33| NotebookEdit | Modifica células em notebooks Jupyter (arquivos `.ipynb`) |~~

35<Note>27<Note>

36 A reversão de arquivo restaura arquivos no disco para um estado anterior. Ela não reverte a conversa em si. O histórico de conversa e o contexto permanecem intactos após chamar `rewindFiles()` (TypeScript) ou `rewind_files()` (Python).28 A reversão de arquivo restaura arquivos no disco para um estado anterior. Ela não reverte a conversa em si. O histórico de conversa e o contexto permanecem intactos após chamar `rewindFiles()` (TypeScript) ou `rewind_files()` (Python).

37</Note>29</Note>

38 30

~~39O sistema de checkpoint rastreia:~~31Quando você reverte para um checkpoint, Claude Code deleta os arquivos que criou e restaura os arquivos que modificou para seu conteúdo naquele ponto. Claude Code ignora um caminho rastreado que é um symlink, hard link ou outro arquivo não-regular. Ele também ignora um arquivo rastreado cujo diretório pai não resolve mais para sua localização no momento do checkpoint, ou cujo backup ele não consegue ler com segurança. [`RewindFilesResult`](/docs/pt/agent-sdk/typescript#rewindfilesresult) conta cada caminho ignorado em seu campo `skippedLinks`. Ignorar requer Claude Code v2.1.216 ou posterior; antes de v2.1.216, uma reversão escrevia e deletava através de links em caminhos rastreados.

~~41* Arquivos criados durante a sessão~~

~~42* Arquivos modificados durante a sessão~~

~~43* O conteúdo original de arquivos modificados~~

~~45Quando você reverte para um checkpoint, os arquivos criados são deletados e os arquivos modificados são restaurados para seu conteúdo naquele ponto.~~

46 32

47<h2 id="implement-checkpointing">33<h2 id="implement-checkpointing">

48 Implementar checkpointing34 Implementar checkpointing

122 let sessionId: string | undefined;108 let sessionId: string | undefined;

123 109

124 // Step 2: Capture checkpoint UUID from the first user message110 // Step 2: Capture checkpoint UUID from the first user message

111 try {

125 for await (const message of response) {112 for await (const message of response) {

126 if (message.type === "user" && message.uuid && !checkpointId) {113 if (message.type === "user" && message.uuid && !checkpointId) {

127 checkpointId = message.uuid;114 checkpointId = message.uuid;

130 sessionId = message.session_id;117 sessionId = message.session_id;

131 }118 }

132 }119 }

120 } catch (error) {

121 // A single-shot query() throws after yielding an error result. If the

122 // failure was an error result, sessionId and checkpointId were already

123 // captured by the loop above; connection or process failures yield no

124 // result message.

125 console.error(`Session ended with an error: ${error}`);

126 }

133 127

134 // Step 3: Later, rewind by resuming the session with an empty prompt128 // Step 3: Later, rewind by resuming the session with an empty prompt

135 if (checkpointId && sessionId) {129 if (checkpointId && sessionId) {

233 ) as client:227 ) as client:

234 await client.query("") # Empty prompt to open the connection228 await client.query("") # Empty prompt to open the connection

235 async for message in client.receive_response():229 async for message in client.receive_response():

230 if checkpoint_id:

236 await client.rewind_files(checkpoint_id)231 await client.rewind_files(checkpoint_id)

237 break232 break

238 ```233 ```

244 });239 });

245 240

246 for await (const msg of rewindQuery) {241 for await (const msg of rewindQuery) {

242 if (checkpointId) {

247 await rewindQuery.rewindFiles(checkpointId);243 await rewindQuery.rewindFiles(checkpointId);

244 }

248 break;245 break;

249 }246 }

250 ```247 ```

251 </CodeGroup>248 </CodeGroup>

252 249

253 Se você capturar o ID de sessão e o ID de checkpoint, você também pode reverter a partir da CLI. Este comando requer o executável `claude`, que vem de [instalar Claude Code](/pt/setup) e não é instalado pelo pacote SDK. O SDK ativa checkpointing para você, mas quando você executa `claude -p` diretamente, você deve definir a variável de ambiente `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`:250 Se você capturar o ID de sessão e o ID de checkpoint, você também pode reverter a partir da CLI. Este comando requer o executável `claude`, que vem de [instalar Claude Code](/docs/pt/setup) e não é instalado pelo pacote SDK. O SDK ativa checkpointing para você, mas quando você executa `claude -p` diretamente, você deve definir a variável de ambiente `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`:

254 251

255 ```bash theme={null}252 ```bash theme={null}

256 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>253 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

257 ```254 ```

258 255

259 O sinalizador `--rewind-files` não aparece na saída de `claude --help`, mas a CLI o aceita conforme mostrado.256 O sinalizador `--rewind-files` não aparece na saída de `claude --help`, mas a CLI o aceita conforme mostrado. Quando a reversão é bem-sucedida, o comando imprime `Files rewound to state at message <checkpoint-uuid>` e sai sem enviar um prompt.

260 </Step>257 </Step>

261</Steps>258</Steps>

262 259

440 const checkpoints: Checkpoint[] = [];437 const checkpoints: Checkpoint[] = [];

441 let sessionId: string | undefined;438 let sessionId: string | undefined;

442 439

440 try {

443 for await (const message of response) {441 for await (const message of response) {

444 if (message.type === "user" && message.uuid) {442 if (message.type === "user" && message.uuid) {

445 checkpoints.push({443 checkpoints.push({

452 sessionId = message.session_id;450 sessionId = message.session_id;

453 }451 }

454 }452 }

453 } catch (error) {

454 // A single-shot query() throws after yielding an error result. If the

455 // failure was an error result, sessionId and the checkpoints array were

456 // already populated by the loop above; connection or process failures

457 // yield no result message.

458 console.error(`Session ended with an error: ${error}`);

459 }

455 460

456 // Later: rewind to any checkpoint by resuming the session461 // Later: rewind to any checkpoint by resuming the session

457 if (checkpoints.length > 0 && sessionId) {462 if (checkpoints.length > 0 && sessionId) {

479 484

480Este exemplo completo cria um pequeno arquivo utilitário, faz o agente adicionar comentários de documentação, mostra as alterações e pergunta se você quer reverter.485Este exemplo completo cria um pequeno arquivo utilitário, faz o agente adicionar comentários de documentação, mostra as alterações e pergunta se você quer reverter.

481 486

482Antes de começar, certifique-se de que você tem o [Claude Agent SDK instalado](/pt/agent-sdk/quickstart).487Antes de começar, certifique-se de que você tem o [Claude Agent SDK instalado](/docs/pt/agent-sdk/quickstart).

483 488

484<Steps>489<Steps>

485 <Step title="Criar um arquivo de teste">490 <Step title="Criar um arquivo de teste">

624 options: opts629 options: opts

625 });630 });

626 631

632 try {

627 for await (const message of response) {633 for await (const message of response) {

628 // Capture the first user message UUID - this is our restore point634 // Capture the first user message UUID - this is our restore point

629 if (message.type === "user" && message.uuid && !checkpointId) {635 if (message.type === "user" && message.uuid && !checkpointId) {

634 sessionId = message.session_id;640 sessionId = message.session_id;

635 }641 }

636 }642 }

643 } catch (error) {

644 // A single-shot query() throws after yielding an error result. If the

645 // failure was an error result, checkpointId and sessionId were already

646 // captured by the loop above; connection or process failures yield no

647 // result message.

648 console.error(`Session ended with an error: ${error}`);

649 }

637 650

638 console.log("Done! Open utils.ts to see the added doc comments.\n");651 console.log("Done! Open utils.ts to see the added doc comments.\n");

639 652

671 main();684 main();

672 ```685 ```

673 </CodeGroup>686 </CodeGroup>

~~674~~

675 Este exemplo demonstra o fluxo de trabalho completo de checkpointing:

~~676~~

677 1. **Ativar checkpointing**: configure o SDK com `enable_file_checkpointing=True` e `permission_mode="acceptEdits"` para aprovar automaticamente edições de arquivo

678 2. **Capturar dados de checkpoint**: conforme o agente é executado, armazene o UUID da primeira mensagem do usuário (seu ponto de restauração) e o ID de sessão

679 3. **Solicitar reversão**: após o agente terminar, verifique seu arquivo utilitário para ver os comentários de documentação e decida se deseja desfazer as alterações

680 4. **Retomar e reverter**: se sim, retome a sessão com um prompt vazio e chame `rewind_files()` para restaurar o arquivo original

681 </Step>687 </Step>

682 688

683 <Step title="Executar o exemplo">689 <Step title="Executar o exemplo">

712O checkpointing de arquivo tem as seguintes limitações:718O checkpointing de arquivo tem as seguintes limitações:

713 719

714| Limitação | Descrição |720| Limitação | Descrição |

715| ------------------------------------------ | ---------------------------------------------------------------- |721| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

716| Apenas ferramentas Write/Edit/NotebookEdit | As alterações feitas através de comandos Bash não são rastreadas |722| Apenas ferramentas Write/Edit/NotebookEdit | As alterações feitas através de comandos Bash não são rastreadas |

723| Edições de subagent | Edições que um [subagent](/docs/pt/agent-sdk/subagents) aplica não são rastreadas ou restauradas, exceto uma skill com `context: fork` executando em primeiro plano; use git para reverter edições não rastreadas |

717| Mesma sessão | Os checkpoints estão vinculados à sessão que os criou |724| Mesma sessão | Os checkpoints estão vinculados à sessão que os criou |

718| Apenas conteúdo de arquivo | Criar, mover ou deletar diretórios não é desfeito pela reversão |725| Apenas conteúdo de arquivo | Criar, mover ou deletar diretórios não é desfeito pela reversão |

719| Arquivos locais | Arquivos remotos ou de rede não são rastreados |726| Arquivos locais | Arquivos remotos ou de rede não são rastreados |

743 750

744**Solução**: Adicione `extra_args={"replay-user-messages": None}` (Python) ou `extraArgs: { 'replay-user-messages': null }` (TypeScript) às suas opções.751**Solução**: Adicione `extra_args={"replay-user-messages": None}` (Python) ou `extraArgs: { 'replay-user-messages': null }` (TypeScript) às suas opções.

745 752

746<h3 id="no-file-checkpoint-found-for-message-error">753<h3 id="no-file-checkpoint-found-for-this-message-error">

747 Erro "No file checkpoint found for message"754 Erro "No file checkpoint found for this message"

748</h3>755</h3>

749 756

750Este erro ocorre quando os dados de checkpoint não existem para o UUID de mensagem do usuário especificado.757Este erro ocorre quando os dados de checkpoint não existem para o UUID de mensagem do usuário especificado.

786 ) as client:793 ) as client:

787 await client.query("")794 await client.query("")

788 async for message in client.receive_response():795 async for message in client.receive_response():

796 if checkpoint_id:

789 await client.rewind_files(checkpoint_id)797 await client.rewind_files(checkpoint_id)

790 break798 break

791 ```799 ```

797 options: { ...opts, resume: sessionId }805 options: { ...opts, resume: sessionId }

798 });806 });

799 807

808 try {

800 for await (const msg of rewindQuery) {809 for await (const msg of rewindQuery) {

810 if (checkpointId) {

801 await rewindQuery.rewindFiles(checkpointId);811 await rewindQuery.rewindFiles(checkpointId);

812 }

802 break;813 break;

803 }814 }

815 } catch (error) {

816 // An error here means the rewind didn't complete, for example the checkpoint

817 // wasn't found or the session couldn't be resumed.

818 console.error(`Rewind session ended with an error: ${error}`);

819 }

804 ```820 ```

805</CodeGroup>821</CodeGroup>

806 822

808 Próximos passos824 Próximos passos

809</h2>825</h2>

810 826

811* **[Sessions](/pt/agent-sdk/sessions)**: aprenda como retomar sessões, o que é necessário para reverter após o fluxo ser concluído. Cobre IDs de sessão, retomada de conversas e bifurcação de sessão.827* **[Sessions](/docs/pt/agent-sdk/sessions)**: aprenda como retomar sessões, o que é necessário para reverter após o fluxo ser concluído. Cobre IDs de sessão, retomada de conversas e bifurcação de sessão.

812* **[Permissions](/pt/agent-sdk/permissions)**: configure quais ferramentas Claude pode usar e como as modificações de arquivo são aprovadas. Útil se você quiser mais controle sobre quando as edições acontecem.828* **[Permissions](/docs/pt/agent-sdk/permissions)**: configure quais ferramentas Claude pode usar e como as modificações de arquivo são aprovadas. Útil se você quiser mais controle sobre quando as edições acontecem.

813* **[TypeScript SDK reference](/pt/agent-sdk/typescript)**: referência completa da API incluindo todas as opções para `query()` e o método `rewindFiles()`.829* **[TypeScript SDK reference](/docs/pt/agent-sdk/typescript)**: referência completa da API incluindo todas as opções para `query()` e o método `rewindFiles()`.

814* **[Python SDK reference](/pt/agent-sdk/python)**: referência completa da API incluindo todas as opções para `ClaudeAgentOptions` e o método `rewind_files()`.830* **[Python SDK reference](/docs/pt/agent-sdk/python)**: referência completa da API incluindo todas as opções para `ClaudeAgentOptions` e o método `rewind_files()`.

agent-sdk/file-checkpointing.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

Rewind de alterações de arquivo com checkpointing

Como o checkpointing funciona

Implementar checkpointing

Ativar checkpointing

Capturar UUID de checkpoint e ID de sessão

Reverter arquivos

Padrões comuns

Checkpoint antes de operações arriscadas

Múltiplos pontos de restauração

Experimente

Criar um arquivo de teste

Executar o exemplo interativo

Executar o exemplo

Limitações

Troubleshooting

Opções de checkpointing não reconhecidas

Mensagens do usuário não têm UUIDs

Erro "No file checkpoint found for this message"

Erro "File rewinding is not enabled"

Erro "ProcessTransport is not ready for writing"

Próximos passos