Limite de 5 horas do Claude Code: revise o encerramento, salve um checkpoint e continue

Quando o Claude Code atinge o limite de cinco horas no meio de uma tarefa, a última resposta não prova que o trabalho terminou. O novo graceful stop é um encerramento de melhor esforço: o agente pode usar uma pequena cota fixa retirada do uso semanal para buscar um ponto de parada mais seguro, mas não promete working tree limpo, commit, testes verdes nem feature concluída.

Siga esta ordem:

1. Leia o tipo exato de limite e o horário de reset.
2. Revise alterações staged, unstaged e untracked.
3. Rode a menor validação que realmente ajude.
4. Crie um checkpoint recuperável no Git.
5. Só então decida entre esperar, ativar usage credits ou continuar por uma API.

Isso transforma uma interrupção incerta em uma passagem de estado controlada e evita pagar para continuar antes de entender como o repositório ficou.

Graceful stop é uma margem de segurança, não uma tarefa pronta

O anúncio do Claude Developers diz que, se o limite de cinco horas chegar no meio da tarefa, o Claude Code tentará encontrar um ponto de parada adequado e receberá uma pequena cota fixa do uso semanal para encerrar o que conseguir. As palavras importantes são tentará e o que conseguir.

Um usuário relatou uma parada mais organizada que os antigos cortes no meio da edição. É um sinal útil, mas continua sendo um relato individual, não uma garantia de confiabilidade.

Separe três mecanismos:

Mecanismo	O que protege	O que não garante
Graceful stop ao atingir o limite	Dá ao agente algum espaço para parar de forma mais coerente	Conclusão, commit, árvore limpa, testes aprovados
Checkpoint do Claude Code	Permite que /rewind restaure muitas edições diretas da sessão	Mudanças via Bash, grande parte das edições de subagents, alterações externas, histórico completo
Checkpoint do Git	Registra um estado revisável, ramificável e recuperável	Correção sem revisão e testes

O encerramento pode deixar um resumo melhor ou menos código pela metade. A aceitação real ainda começa no Git.

Primeiro, descubra qual limite interrompeu a tarefa

Nem todo bloqueio some em cinco horas. A documentação de limites de uso separa limites de uso de limites de contexto, e o consumo pode ser compartilhado entre superfícies Claude ligadas à mesma conta.

Leia a mensagem literalmente:

• Approaching 5-hour limit: ainda há uma janela curta para parar de ampliar o escopo e preparar o checkpoint.
• 5-hour limit reached — resets …: use o horário mostrado como referência.
• Um limite semanal ou específico de modelo pode continuar depois do reset da janela de cinco horas.
• Erro de capacidade ou serviço é diferente de uso esgotado; pagar mais não corrige indisponibilidade.

Se o cliente interativo atual oferecer manter a sessão aberta, esperar e continuar automaticamente após o reset, esse pode ser o caminho mais simples. Confirme o aviso da sua versão e do seu modo: sair pode encerrar a espera, e modos background, print ou com API key podem se comportar de outro jeito.

Inspecione o repositório antes de pedir mais trabalho

Na raiz do repositório, rode comandos somente de leitura:

git status --short --branch
git diff --stat
git diff
git diff --cached
git ls-files --others --exclude-standard

O /diff do Claude Code também ajuda, mas o Git continua sendo a fonte de verdade do working tree.

Antes de prosseguir, responda:

1. Quais arquivos mudaram?
2. O que está staged, unstaged e untracked?
3. Há uma edição pela metade, como uma nova chamada sem atualização de tipo, teste ou migração?
4. Algum lockfile, arquivo gerado, configuração ou migração mudou sem necessidade?
5. Qual é o menor comando capaz de revelar o problema principal?

Rode a validação real do projeto:

# Exemplos: use o menor comando relevante do seu repositório
npm test -- path/to/affected.test.ts
pytest tests/test_affected.py -q
cargo test affected_module
git diff --check

Uma parada segura não é “Claude escreveu um resumo”. É conseguir explicar quais arquivos mudaram, o que falta, qual foi o resultado da validação e qual é o próximo passo pequeno.

Se o diff estiver confuso, não peça “termine tudo”. Salve primeiro um checkpoint.

Crie um checkpoint recuperável por um destes métodos

Método 1: commit WIP local e revisado

Use quando o estado atual já for coerente e commits temporários forem aceitáveis em uma branch local.

git status --short --branch
git add -p
# Adicione explicitamente novos arquivos já revisados.
git add -- path/to/reviewed-new-file
git diff --cached --check
git diff --cached
# Rode aqui o menor teste ou lint relacionado.
git commit -m "WIP: checkpoint before Claude Code limit reset"
git rev-parse --short HEAD

Não rode git add -A no automático. Revise .env, credenciais, fixtures privadas, artefatos gerados, binários grandes e dumps de debug. Um WIP local é ponto de recuperação, não autorização para push em branch protegida.

Registre também uma nota curta:

Objetivo: concluir a validação de expiração do token
Checkpoint: a1b2c3d
Alterados: auth_service.py, tests/test_auth.py
Validação: teste direcionado falha; esperado 401, recebido 200
Próximo passo: revisar a comparação de expiração antes de mudar callers

Método 2: patches e arquivos untracked revisados fora do repositório

Use esta opção quando não quiser criar um commit. O script resolve primeiro o caminho real de CLAUDE_CHECKPOINT_DIR; se ele estiver dentro do repositório, inclusive por meio de link simbólico, a execução para antes de criar qualquer arquivo de checkpoint.

São três etapas: primeiro, inspecione sem salvar os candidatos staged, unstaged e untracked e seus diffs; depois, selecione explicitamente os números dos caminhos em cada grupo, deixando tudo o que não foi escolhido claramente excluído; por fim, nada é gravado até você digitar SAVE REVIEWED. Antes de selecionar, revise o diff completo ou o arquivo untracked e exclua chaves, dados privados e qualquer conteúdo que não deva ser preservado. Se apenas parte de um arquivo puder ser salva com segurança, separe a alteração ou use o commit WIP acima, em vez de selecionar o arquivo inteiro.

O método externo interrompe a execução ao detectar a renomeação de um arquivo rastreado; nesse caso, use um commit WIP revisado. Se um caminho unstaged selecionado também tiver alterações staged, revise e salve as duas versões. Antes de restaurar, defina checkpoint como o diretório absoluto exibido na etapa de salvamento. Uma base diferente, uma árvore de trabalho com alterações ou qualquer falha interrompe a restauração.

repo_root="$(git rev-parse --show-toplevel)"
cd "$repo_root"

# Step 1: inspect everything. These commands do not save files.
git status --short --branch
git diff --cached
git diff
git ls-files --others --exclude-standard

# Steps 2-3: choose reviewed paths explicitly, then save only that scope.
python3 /dev/fd/3 3<<'PY'
from datetime import datetime, timezone
from pathlib import Path
import json, os, shlex, subprocess, tarfile


def git(*args):
    return subprocess.run(["git", *args], check=True, stdout=subprocess.PIPE).stdout


def path_list(*args):
    return list(dict.fromkeys(Path(os.fsdecode(x)) for x in git(*args).split(b"\0") if x))


def choose(label, items):
    print(f"\n{label} candidates:")
    if not items:
        print("  (none)")
        return []
    for i, path in enumerate(items, 1):
        print(f"  {i:>3}  {shlex.quote(os.fspath(path))}")
    answer = input(
        "Select reviewed numbers to save "
        "(1,3-5; 'all'; blank saves none): "
    ).strip().lower()
    if not answer:
        return []
    if answer == "all":
        return items[:]
    chosen = set()
    try:
        for token in answer.split(","):
            bounds = [int(x) for x in token.strip().split("-", 1)]
            chosen.update(range(min(bounds), max(bounds) + 1))
    except ValueError as exc:
        raise SystemExit("Invalid selection; nothing was saved.") from exc
    if not chosen or min(chosen) < 1 or max(chosen) > len(items):
        raise SystemExit("Selection is outside the displayed range; nothing was saved.")
    return [path for i, path in enumerate(items, 1) if i in chosen]


def patch(cached, items):
    if not items:
        return b""
    args = ["diff"] + (["--cached"] if cached else [])
    return git(*args, "--binary", "--", *(os.fspath(path) for path in items))


repo = Path(git("rev-parse", "--show-toplevel").decode().rstrip("\n")).resolve()
root = Path(os.environ.get(
    "CLAUDE_CHECKPOINT_DIR", os.fspath(Path.home() / "claude-checkpoints")
)).expanduser().resolve(strict=False)
if root == repo or repo in root.parents:
    raise SystemExit("CLAUDE_CHECKPOINT_DIR must resolve outside the repository.")
root.mkdir(parents=True, exist_ok=True)
root = root.resolve()
if root == repo or repo in root.parents:
    raise SystemExit("CLAUDE_CHECKPOINT_DIR must resolve outside the repository.")

# A path-only selection cannot represent both sides of a detected rename.
if (git("diff", "--cached", "--find-renames", "--diff-filter=R", "--name-only", "-z")
        or git("diff", "--find-renames", "--diff-filter=R", "--name-only", "-z")):
    raise SystemExit("Renames require a reviewed WIP commit; nothing was saved.")

candidates = {
    "staged": path_list("diff", "--cached", "--name-only", "-z"),
    "unstaged": path_list("diff", "--name-only", "-z"),
    "untracked": path_list("ls-files", "--others", "--exclude-standard", "-z"),
}
if not any(candidates.values()):
    raise SystemExit("No staged, unstaged, or untracked changes were found.")
selected = {name: choose(name, items) for name, items in candidates.items()}
if not any(selected.values()):
    raise SystemExit("No reviewed changes were selected; nothing was saved.")
missing_baseline = set(selected["unstaged"]) & (
    set(candidates["staged"]) - set(selected["staged"])
)
if missing_baseline:
    raise SystemExit(
        "Selected unstaged paths also have staged changes. Select both reviewed "
        "versions or use a WIP commit; nothing was saved."
    )

not_saved = {
    name: [path for path in candidates[name] if path not in selected[name]]
    for name in candidates
}

print("\nSelected for saving:")
for name, items in selected.items():
    print(f"  {name}: " + (", ".join(shlex.quote(os.fspath(p)) for p in items) or "(none)"))
print("Excluded and NOT saved:")
for name, items in not_saved.items():
    print(f"  {name}: " + (", ".join(shlex.quote(os.fspath(p)) for p in items) or "(none)"))
if input("Type SAVE REVIEWED to save exactly this scope: ").strip() != "SAVE REVIEWED":
    raise SystemExit("Confirmation did not match; nothing was saved.")

current = {
    "staged": path_list("diff", "--cached", "--name-only", "-z"),
    "unstaged": path_list("diff", "--name-only", "-z"),
    "untracked": path_list("ls-files", "--others", "--exclude-standard", "-z"),
}
if current != candidates:
    raise SystemExit("The candidate list changed during review; rerun from step 1.")

stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
checkpoint = (root / f"{repo.name}-claude-{stamp}").resolve(strict=False)
if checkpoint == repo or repo in checkpoint.parents:
    raise SystemExit("Checkpoint path unexpectedly resolves inside the repository.")
checkpoint.mkdir(exist_ok=False)
(checkpoint / "base-commit.txt").write_bytes(git("rev-parse", "HEAD"))
(checkpoint / "status.txt").write_bytes(git("status", "--short", "--branch"))
(checkpoint / "staged.patch").write_bytes(patch(True, selected["staged"]))
(checkpoint / "unstaged.patch").write_bytes(patch(False, selected["unstaged"]))
(checkpoint / "untracked.list0").write_bytes(b"".join(
    os.fsencode(os.fspath(path)) + b"\0" for path in selected["untracked"]
))

manifest = {
    "selected": {name: [os.fspath(p) for p in items] for name, items in selected.items()},
    "not_saved": {name: [os.fspath(p) for p in items] for name, items in not_saved.items()},
}
(checkpoint / "selection.json").write_text(
    json.dumps(manifest, ensure_ascii=True, indent=2) + "\n", encoding="utf-8"
)
omitted = [
    f"{name}\t{json.dumps(os.fspath(path), ensure_ascii=True)}"
    for name, items in not_saved.items() for path in items
]
(checkpoint / "not-saved.txt").write_text(
    "\n".join(omitted) + ("\n" if omitted else "(none)\n"), encoding="utf-8"
)
if selected["untracked"]:
    with tarfile.open(checkpoint / "untracked.tar.gz", "w:gz", dereference=False) as archive:
        for path in selected["untracked"]:
            archive.add(repo / path, arcname=path.as_posix(), recursive=False)

partial = bool(omitted)
(checkpoint / "scope.txt").write_text(
    "PARTIAL: see not-saved.txt; this is not a complete recovery point.\n"
    if partial else
    "REVIEWED SCOPE: every listed candidate was saved; ignored files remain outside scope.\n",
    encoding="utf-8",
)
print(("PARTIAL checkpoint" if partial else "Reviewed checkpoint") + f" saved to {checkpoint}")
if partial:
    print("Some listed changes were not saved; read not-saved.txt before recovery.")
PY

selection.json registra os caminhos selecionados e excluídos, not-saved.txt lista cada item omitido e scope.txt declara o escopo. Se qualquer candidato staged, unstaged ou untracked for excluído, o terminal e scope.txt marcam o resultado como PARTIAL; ele não é um ponto de recuperação completo e restaura apenas o escopo selecionado. Arquivos ignored continuam fora do escopo, e o checkpoint não prova que o código funciona.

Antes de restaurar, leia scope.txt e not-saved.txt. Restaure somente o escopo salvo em um checkout limpo no commit base registrado:

(
    set -eu
    checkpoint="/absolute/path/printed-by-the-save-step" # Replace with the actual checkpoint directory.
    test -d "$checkpoint"
    repo_root="$(git rev-parse --show-toplevel)"
    cd "$repo_root"
    for required in base-commit.txt scope.txt not-saved.txt staged.patch unstaged.patch untracked.list0; do
        test -f "$checkpoint/$required"
    done
    cat "$checkpoint/scope.txt" "$checkpoint/not-saved.txt"
    test "$(git rev-parse HEAD)" = "$(cat "$checkpoint/base-commit.txt")"
    test -z "$(git status --porcelain --untracked-files=all)"
    if [ -s "$checkpoint/staged.patch" ]; then
        git apply --index "$checkpoint/staged.patch"
    fi
    if [ -s "$checkpoint/unstaged.patch" ]; then
        git apply "$checkpoint/unstaged.patch"
    fi
    if [ -s "$checkpoint/untracked.list0" ]; then
        tar -xzkf "$checkpoint/untracked.tar.gz"
    fi
    git status --short
)

Se o repositório já estiver em outra base, não force os patches. Crie uma branch ou worktree limpa no commit salvo, restaure ali e faça a integração de forma consciente.

Use checkpoints do Claude Code, mas não no lugar do Git

A documentação oficial de checkpointing informa que o Claude Code acompanha edições diretas de arquivos na sessão e permite revisá-las ou restaurá-las com /rewind. Ela descreve a retenção dos 100 checkpoints mais recentes da sessão e sua associação à conversation, o que pode mantê-los disponíveis depois de retomá-la.

Isso é útil para desfazer um turno ruim do agente, mas não é backup do repositório. As limitações documentadas incluem mudanças feitas por Bash, a maioria das edições de subagents, alterações externas concorrentes e alguns casos com symlink ou hardlink. O Git oferece commit ID durável, branches, patches revisáveis e recuperação independente da sessão.

Use as duas camadas:

• /rewind para rollback rápido na sessão;
• commit no Git ou bundle externo para checkpoint durável.

A referência da CLI documenta:

claude -c
claude -r "<session>"

Depois de retomar, rode git status outra vez antes de autorizar edições. Recuperar a conversation não prova que os arquivos continuam iguais ao resumo anterior.

Escolha esperar, usage credits ou API só depois do checkpoint

Situação	Primeira escolha	Motivo
Reset próximo, checkpoint seguro e prazo permite pausa	Esperar	Sem cobrança medida adicional nem troca de autenticação
Precisa da mesma interface e conversation e aceita gasto medido	Usage credits	Contas elegíveis podem continuar depois do uso incluído
Precisa de key, saldo ou orçamento de projeto separados	API	Separa cobrança e autenticação da assinatura
Limites interrompem vários dias normais de trabalho	Rever plano e fluxo	Uma única interrupção não justifica upgrade permanente

Espere quando a pausa custar menos que a troca de rota

Se o reset estiver perto e o checkpoint pronto, esperar costuma ser mais seguro. Anote o horário e deixe o handoff. Mantenha a sessão aberta apenas se o cliente oferecer explicitamente espera e retomada.

Ao voltar:

git status --short --branch
git diff --stat

Depois descreva o próximo passo. Um simples “continue” obriga o agente a adivinhar o estado.

Use usage credits quando a continuidade for prioridade

A documentação de usage credits diz que usuários Pro e Max elegíveis podem ativar uso extra pay-as-you-go em Settings > Usage, adicionar fundos e configurar controles. A cobrança é separada da assinatura e as janelas normais de cinco horas continuam sendo resetadas.

Antes de ativar:

• defina limite mensal e alertas;
• decida se auto-reload é aceitável;
• confirme que a interface mostra continuação com usage credits;
• pare depois do checkpoint urgente ou teste de aceitação.

É conveniente para manter interface e contexto, mas não é saldo gratuito da assinatura.

Use API quando precisar separar autenticação ou orçamento

API é outra rota de autenticação e cobrança. Ela não herda automaticamente a cota da assinatura, e trocar uma variável pode não substituir um login salvo. No Claude Code, confira /status, confirme provider ou gateway e localize o request no log de uso do fornecedor.

BetterToken é uma API compatível com Anthropic e pay-as-you-go, não uma extensão da assinatura Claude. Pode servir para key e saldo separados, mas checkpoint e handoff continuam essenciais com qualquer fornecedor.

Compare preços API do mesmo modelo, não o custo total da tarefa

Os preços padrão de texto abaixo foram verificados em 2026-10-01. A unidade é USD por um milhão de tokens. Os valores da Anthropic vêm da página oficial de API pricing; os do BetterToken, da página de preços.

ID exato do modelo	Entrada Anthropic	Saída Anthropic	Entrada BetterToken	Saída BetterToken
claude-opus-5-5	$4.00	$20.00	$2.72	$13.60
claude-sonnet-5	$2.00	$10.00	$1.36	$6.80
claude-haiku-4-5-20251001	$1.00	$5.00	$0.68	$3.40

A tabela responde apenas ao preço padrão de entrada e saída do mesmo model ID nessa data. Ela não torna equivalentes:

• uso de assinatura, uma cota incluída sujeita aos limites do plano;
• usage credits, continuação medida em interfaces Claude elegíveis;
• uso de API, cobrado em outra conta por tokens e recursos aplicáveis.

O custo real depende de tokens de entrada e saída, cache, contexto longo ou fast mode, retries, tool calls e regras da conta. Preço de lista menor não prova que sua tarefa completa será mais barata.

Retome com um handoff verificável, não apenas “continue”

Prepare um resumo curto para a próxima sessão:

Objetivo: o que precisa ser verdade ao terminar
Base: branch e commit/checkpoint ID
Mudanças: staged, unstaged e untracked
Validação: comandos exatos e resultados
Falha conhecida: erro ou assertion precisa
Não tocar: arquivos sensíveis ou fora do escopo
Próxima ação: um passo pequeno e testável

Peça primeiro que o Claude Code inspecione o diff e repita a próxima ação. Isso revela branch diferente, resumo antigo ou encerramento incompleto antes de criar novas mudanças.

Perguntas frequentes

Graceful stop cria commit automaticamente?

Não. A declaração oficial promete tentar parar de forma mais segura, não criar um commit no Git.

Ele garante que a tarefa terminou?

Não. Pode parar com trabalho pendente ou depois de apenas parte das alterações. Testes e critérios de aceitação continuam decidindo.

O encerramento custa dinheiro extra?

A pequena cota fixa anunciada vem do uso semanal. Usage credits e API são rotas medidas separadas; confira o modo de cobrança da conta.

/rewind substitui o Git?

Não. Ele ajuda com edições diretas da sessão, mas as exclusões documentadas deixam mudanças do repositório de fora.

E se a mensagem citar weekly limit?

O reset de cinco horas pode não removê-lo. Salve o checkpoint, siga o tipo e horário mostrados no cliente e confirme qual contador bloqueia você antes de comprar uso adicional.