compact-ops

Três passos

1. claude plugin install compact-ops Clone o repo, adicione como marketplace local, instale. Uma vez só.
2. /compact Compacte como sempre. O PreCompact faz backup do transcript e grava o arquivo de estado sozinho.
3. recuperação injetada O contexto novo recebe o estado, uma nota para reler os originais e a lista de skills invocadas.

Para quem é

• Usuários intensivos de Claude Code com sessões que cruzam uma ou mais compactações por dia
• Operadores de agentes que rodam sessões longas ou agendadas e as retomam no dia seguinte com claude --resume
• Times que passam sessões adiante o arquivo de estado é Markdown puro que um humano lê como nota de handoff
• Autores de hooks um exemplo completo de plugin feito só com hooks oficiais, fail-open do início ao fim

Quando usar

• Quando o auto-compact já engoliu uma decisão no meio da tarefa: o aviso aos 60% deixa você escolher o momento
• Antes de trabalhos de vários dias: o estado sobrevive à compactação, ao fechamento da sessão e a um reboot do PC
• Quando o agente pede de novo uma aprovação que já tinha, ou repete uma abordagem que já falhou: são exatamente as seções fixas do arquivo de estado
• Se você já disse a um agente pós-compact "isso a gente já decidiu", este plugin existe para esse incidente

Instalação

git clone https://github.com/kenimo49/compact-ops.git
claude plugin marketplace add /path/to/compact-ops --scope user
claude plugin install compact-ops@compact-ops-local

Requer Claude Code v2.x, jq e o CLI claude como backend de LLM. Suporta Linux e macOS. Depois de instalar, basta rodar /compact normalmente; os hooks cuidam do resto.

O que ele faz

• PreCompact: faz backup do transcript (gzip, o JSONL encolhe para cerca de 1/10) e um LLM grava um arquivo de estado com 10 seções: plano ativo, decisões, bloqueios, arquivos em edição e tentativas que falharam
• Logo após a compactação: injeta no contexto novo o arquivo de estado, uma nota para reler os originais e a lista de skills já invocadas
• No claude --resume: a mesma injeção de recuperação, com fallback para o estado mais recente do projeto em até 72 horas, sobrevivendo a um reboot do PC
• Aviso de uso de contexto calculado pelo próprio plugin (padrão 60%): recomenda /compact uma única vez, com recitação de 3 linhas do plano, da fase e da última decisão
• O estado persiste em ~/.claude/compact-ops/ com retenção de 30 dias, organizado por projeto; o session_id passa por validação de allowlist antes de virar caminho de arquivo
• A saída do LLM é validada nas 10 seções antes de ser gravada; saída inválida mantém o estado anterior e falha aberto
• Derivado de u-ichi/compact-plus (MIT), tornado autocontido: sem scripts externos de statusline e com backends de LLM só em Claude (Sonnet primário, Haiku de fallback)

Com e sem compact-ops

Mesmo algoritmo de compactação, mesmo summary embutido. A diferença é tudo o que está em volta.

Fonte: o README do projeto. O algoritmo de compressão fica intocado; tudo é hook oficial acoplado por fora.

Como fica o arquivo de estado

Uso

# compacte normalmente, os hooks cuidam do resto
/compact

# argumentos viram orientação prioritária para o gerador de estado
/compact guarde todas as decisões de design

# ajuste pelo bloco env do ~/.claude/settings.json
COMPACT_OPS_WARN_THRESHOLD=70
COMPACT_OPS_PRIMARY_BACKEND=""
COMPACT_OPS_DEBUG=1

Testado em campo no próprio lançamento

O primeiro beneficiário foi a sessão que o construiu. Três momentos de uso real, sem encenação:

• Durante o trabalho de release da v0.2.0, o próprio aviso de 60% disparou aos 67% dentro da sessão que fazia o release: o autor escreveu o aviso e foi salvo por ele na mesma noite.
• Minutos depois, uma reorganização de diretórios quebrou três dos seus hooks no meio da sessão. A compactação completou intacta mesmo assim, porque todo hook é fail-open: o modo de falha foi testado em produção por acidente.
• Esta página que você está lendo foi revisada em uma sessão que cruzou duas compactações, retomando a cada vez do arquivo de estado que ela descreve.

O log do dia do lançamento, incluindo o aviso de 67% e a falha tripla de hooks, está escrito por inteiro no blog do projeto.

O log real do lançamento →

Custos a conhecer: cada compact adiciona uma chamada de LLM para gerar o estado (padrão Sonnet; dá para trocar por Haiku ou desativar via env). Arquivos de estado e backups guardam a conversa na íntegra; são criados com umask 077 (diretórios 700, arquivos 600), ficam na sua máquina e são apagados automaticamente após 30 dias.

Por que este plugin existe

O summary embutido lida bem com código. O que ele derruba são fatos operacionais: "o push já foi aprovado", "essa abordagem já foi tentada e falhou", "esse número veio daquele arquivo". Quando isso some, o agente pede aprovações de novo, repete becos sem saída, e você paga duas vezes pelo mesmo trabalho. O compact-ops dá a esses fatos seções fixas próprias e os guarda fora do summary. Uma linha de design foi inegociável: o arquivo de estado nunca é tratado como mais confiável que os arquivos do projeto. Um resumo de LLM aceito às cegas por outro LLM é só um telefone sem fio acelerado, então a orientação de recuperação sempre aponta de volta para os originais.

Ao lado do compact-plus e do Claude Code puro

O compact-ops é um derivado de u-ichi/compact-plus (MIT), que foi pioneiro na ideia de gravar estado estruturado antes do compact. As diferenças abaixo são as razões de o derivado existir.

A ideia central, um hook PreCompact chamando um segundo LLM para gravar estado estruturado, vem do compact-plus. A tabela lista as diferenças documentadas no README em julho de 2026; se as premissas batem com o seu ambiente, o compact-plus é uma boa escolha.

FAQ

Sobre o autor

Criado por Ken Imoto: mais de 300 artigos técnicos em Zenn, Qiita, Dev.to e neste site, mais de 40 livros em 4 idiomas, mais de 400 mil pageviews em Zenn e Qiita, 4 artigos de pesquisa no Zenodo e criador do LLMO Framework.

Mais sobre Ken →