Reelier

---

Seu agente rederiva o mesmo fluxo de trabalho a cada execução — queimando tokens e silenciosamente se desviando. O Reelier compila uma execução que funcionou em um arquivo SKILL.md que reproduz deterministicamente (sem LLM, 0 tokens, cada passo verificado em um recibo) e, em seguida, compara execuções para detectar o dia em que para de corresponder. Para agentes em fluxos de trabalho de produção recorrentes — onde "executou" não é prova.

Instale → seu primeiro recibo em 60 segundos

npm i -g reelier && reelier init

reelier init primeiro escaneia o trabalho que você já fez — no Claude Code, Codex, Windsurf e OpenClaw — e se oferece para transformar uma sessão real passada em uma habilidade reproduzível. Sem esse histórico? Ele executa uma demonstração sem configuração e termina com um recibo real:

Your receipt:
  skill:        reelier-init-demo
  steps:        2 total, 2 passed, 0 unchecked, 0 failed
  replay time:  44ms  [measured]
  LLM tokens:   0     [measured]

  An agent doing a comparable task re-reasons every run (~2.8s, ~18k tokens on
  our benchmark). Your replay: 44ms, 0 tokens.

Ou execute com Docker — sem instalar o Node

docker run --rm ghcr.io/seldonframe/reelier --help

# Replay a skill from the current directory:
docker run --rm -v "$PWD:/work" -w /work ghcr.io/seldonframe/reelier run my.skill.md

# Record from your agent history (mount it read-only):
docker run --rm -v "$HOME/.claude:/root/.claude:ro" -v "$PWD:/work" -w /work \
  ghcr.io/seldonframe/reelier scan

Por quê

• Seu agente reaprende o trabalho a cada execução — e então silenciosamente se desvia. Cada execução rederiva o fluxo de trabalho, e cada pequena correção "racional" se acumula — o que operadores de longo prazo chamam de tecido cicatricial. Uma habilidade compilada nunca reaprende e não pode se desviar.
• O problema real é a conta. "Quanto isso custou?" é a primeira resposta que toda execução longa de agente recebe. O Reelier reproduz por 0 tokens, com um recibo.
• Não é RPA frágil. Reproduz chamadas de ferramentas (JSON tipado de entrada/saída), não pixels — e cada passo carrega sua própria asserção, então um passo quebrado falha ruidosamente, nunca passa silenciosamente.
• Atualizou o modelo? Uma reprodução é fixada — regrave no novo modelo e reelier diff contra sua linha de base congelada: IGUAL ou DESVIOU, por passo, antes de chegar à produção.
• "Qualquer coisa determinística deveria ser apenas código." Concordo — seu agente já o escreveu. O Reelier captura sua execução real e funcional em um arquivo testado. Determinismo sem a codificação manual.

Como funciona — gravar → compilar → reproduzir → comparar → recibo

reelier init                        # 60s: record → compile → replay → your receipt
reelier run  <name>.skill.md        # replay deterministically — 0 tokens (read-only by default)
reelier diff <name>                 # SAME or DRIFTED, per step — exit 1 on drift
reelier push <name>.skill.md        # sync receipts to your ledger (opt-in)

1. Gravar — três maneiras: reelier mcp --wrap "<your mcp server>" (um proxy sem perdas na frente das ferramentas do seu agente), diretamente de uma sessão existente (reelier scan / reelier from-session), ou o reelier init guiado.
2. Compilar — reelier compile transforma um rastreamento em um SKILL.md deterministicamente (0 chamadas LLM) — uma receita com uma asserção em cada passo, e as lacunas honestas do compilador impressas como Perguntas em aberto (incluindo datas literais, UUIDs e timestamps que ele sinaliza como "isso deveria ser uma variável?") em vez de adivinhar.
3. Reproduzir — reelier run executa no Nível 0: sem LLM, milissegundos, byte-idêntico. Somente leitura por padrão — um passo de escrita (idempotent-write) nunca é reexecutado a menos que você passe --allow-writes.
4. Comparar — reelier diff compara duas execuções de uma habilidade e relata IGUAL ou DESVIOU por passo, com a asserção com falha como o porquê. Código de saída 1 no desvio, então ele controla uma reprodução agendada.
5. Recibo — cada execução é um recibo (resultados por passo, tempo, 0 tokens). reelier push opcionalmente os sincroniza com um livro-razão de recibos para um link permanente compartilhável + um selo reprodução-verificada incorporável.

Converter uma Habilidade de Agente

Transforme uma habilidade de instrução + uma execução gravada em uma reprodução determinística — sua habilidade, menos o modelo:

reelier mcp --wrap "<your mcp server>"                 # record: agent runs the skill's task once
reelier compile trace.jsonl --from-skill ./my-skill/SKILL.md
# → my-skill.skill.md — name + description carried from your SKILL.md,
#   steps ONLY from the recorded run (never generated from instruction text)

Importar sessões de qualquer agente

Você já tem fluxos de trabalho reproduzíveis nos próprios logs de sessão do seu agente. reelier scan os encontra; reelier from-session transforma um em uma habilidade. O formato é detectado a partir do conteúdo do arquivo — nenhuma flag necessária para os agentes suportados:

reelier scan                                          # discovers sessions from every known agent under your home dir
reelier from-session ~/.claude/projects/*/*.jsonl      # Claude Code
reelier from-session ~/.codex/sessions/**/rollout-*.jsonl   # Codex CLI
reelier from-session ~/.openclaw/agents/*/sessions/*.jsonl  # OpenClaw

Agente	Local da sessão	Status
Claude Code	~/.claude/projects/<project>/<uuid>.jsonl	suportado
Codex CLI	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	suportado
OpenClaw	~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl	suportado
Cursor	.../User/globalStorage/state.vscdb (SQLite, não documentado)	detectado, ainda não analisável
Windsurf	.../User/globalStorage/state.vscdb (SQLite, não documentado)	detectado, ainda não analisável

Apenas chamadas reproduzíveis (os builtins do próprio Reelier, ou chamadas mcp__<server>__<tool>) são compiladas em uma habilidade — ações nativas de arquivo/shell/busca são relatadas como ignoradas, nunca fabricadas em um passo. Passe --agent <claude-code|codex|openclaw> para forçar um formato em vez da detecção automática; reelier scan / reelier from-session --agent cursor (ou --agent windsurf) relatam o que está no disco honestamente, em vez de adivinhar um formato binário não documentado.

Três testes, uma habilidade

Uma habilidade gravada oferece três perguntas diferentes para fazer a ela, não uma:

• Determinismo — reelier run <skill.md> reproduz contra as asserções que você gravou. Mesmos passos, mesmas verificações, 0 tokens. Responde: isso ainda faz o que fazia?
• Recuperação — reelier run <skill.md> --fail N[=status] injeta uma falha sintética no passo N (status padrão 500; sobrescreva com --fail N=429, repetível) em vez de despachar a chamada de ferramenta real desse passo, e então executa a MESMA escada de escalonamento que uma falha real atingiria. Nada fora da rede realmente acontece — um passo simulado nunca chama sua ferramenta, então você pode testar a recuperação de um passo de escrita sem --allow-writes e sem efeito colateral. Responde: se isso quebrasse, a habilidade perceberia e se recuperaria? (Uma execução simulada é apenas um teste local — reelier push se recusa a publicar uma; veja abaixo.)
• Desvio — reelier run <skill.md> --wrap "<your mcp server>" reproduz contra suas dependências vivas e somente leitura, em vez do rastreamento gravado. Emparelhado com reelier manifest (abaixo), é assim que você detecta o esquema de uma ferramenta mudando sob você antes que uma reprodução real o faça.

Taxonomia devida à revisão de Mads Hansen do post de lançamento.

Desvio de esquema de ferramenta: reelier manifest

Os passos de uma habilidade chamam ferramentas específicas com formatos de argumentos específicos. Se o esquema de ferramenta de um servidor MCP empacotado mudar desde que você gravou contra ele, a reprodução deve recusar ruidosamente, não preencher silenciosamente os argumentos errados. reelier manifest carimba um resumo de esquema para cada ferramenta que os passos da habilidade realmente usam:

reelier manifest <skill.md> --wrap "<your mcp server>"   # stamp/refresh the manifest from live servers
reelier run <skill.md> --wrap "<your mcp server>"         # preflight checks the manifest BEFORE step 1 runs

Se o esquema de uma ferramenta carimbada tiver se desviado (ou a ferramenta não existir mais), reelier run falha fechado — MANIFEST DRIFT — refusing to replay — antes que qualquer coisa execute. --ignore-manifest é a sobrescritura explícita de quebra de vidro para quando você sabe que o desvio é aceitável; ainda é registrado na execução (manifestIgnored: true), então nunca é um desvio silencioso. Uma habilidade sem manifesto algum recebe apenas uma nota consultiva — toda habilidade pré-manifesto continua funcionando sem modificações.

Aprovação de escrita por passo: reelier approve

--allow-writes/--yes são flags genéricas — elas dizem "esta execução pode escrever", não "esta escrita exata é revisada". reelier approve vincula por hash a aprovação ao modelo de ferramenta + argumento de um passo específico:

reelier approve <skill.md>          # walk each write/destructive step, y/N to approve
reelier approve <skill.md> --all    # approve every write step non-interactively

Um passo aprovado cuja ferramenta/argumentos ainda correspondem ao seu hash carimbado é executado sem flags alguma. Se a ferramenta ou os argumentos do passo mudaram desde a aprovação, a reprodução falha fechado — Approval mismatch — e nenhuma flag a sobrescreve; você revisa e reaprova novamente. Um passo de escrita sem campo approve: mantém o comportamento exato de --allow-writes/--yes de hoje, inalterado.

Verifique o valor, não apenas a forma

As asserções de uma habilidade são o que tornam uma reprodução prova. A gramática verifica status, estrutura, e valor:

- assert: status == 200
- assert: json.results is array
- assert: json.count >= 1              # numeric range
- assert: json.plan is string          # type
- assert: json.id matches /^usr_/      # value pattern
- assert: body contains "ok"

Use-o dentro do seu agente de codificação (MCP)

reelier serve expõe os próprios comandos do Reelier como ferramentas MCP, para que Claude Code / Cursor / Windsurf / Codex possam chamá-lo no meio da sessão:

{ "mcpServers": { "reelier": { "command": "npx", "args": ["-y", "reelier", "serve"] } } }

O agente recebe reelier_scan, reelier_from_session, reelier_replay, reelier_diff e reelier_push — com descrições que dizem exatamente quando usar cada um (e quando não usar). Ele grava uma tarefa determinística uma vez e depois reproduz em vez de re-raciocinar.

Ferramentas

• reelier_scan — escaneia o histórico de sessão do agente (Claude Code, Codex, Windsurf, OpenClaw) em busca de fluxos de chamada de ferramentas reproduzíveis
• reelier_from_session — compila uma sessão gravada em um SKILL.md reproduzível com uma asserção em cada passo
• reelier_replay — reproduz uma habilidade deterministicamente com 0 tokens LLM (somente leitura por padrão; escritas controladas por --allow-writes)
• reelier_diff — compara duas execuções: IGUAL ou DESVIOU por passo, com a asserção com falha como o porquê; sai com 1 no desvio
• reelier_push — sincroniza um recibo de execução com o livro-razão para um link permanente compartilhável (opt-in)

A prova medida

De um benchmark real, direto e comparativo (agente vs. Reelier, mesma tarefa, mesmos dados) — tabelas completas + metodologia em examples/benchmark:

• 1.000 / 1.000 reproduções byte-idênticas (teste de variância de cauda N=1000)
• 0 tokens por reprodução — verificado a partir do registro de execução, não assumido
• ~50× mais barato (US$ 0,000000/reprodução vs. US$ 0,019068/execução em média no braço do agente)
• ~59× mais rápido (48ms vs. 2.842ms de latência média)
• um desvio real auto-recuperado por ~US$ 0,001, uma vez, e depois gratuito em cada reprodução seguinte

A latência varia conforme a rede — A reprodução de Nível 0 reexecuta as chamadas de ferramenta da habilidade, então o tempo real depende da sua conexão. O que não varia: 0 tokens LLM, os mesmos passos a cada execução e o recibo. Corroborado independentemente — arXiv 2605.14237 encontrou 93,3–99,98% de redução de tokens para o mesmo padrão de gravar-e-reproduzir.

Funciona com qualquer modelo (BYOK)

A reprodução de Nível 0 (o padrão) nunca chama um modelo — 0 tokens, por construção. O escalonamento (--max-level 1|2) é opt-in e se comunica através de uma superfície BYOK estreita (--llm-base-url + --llm-model): um adaptador nativo Anthropic Messages e um adaptador compatível com OpenAI para todo o resto (OpenRouter, Ollama, endpoint OpenAI do Gemini, Groq, vLLM, LM Studio, Kimi, …). Aponte-o para um modelo mais forte e a próxima auto-recuperação de cada habilidade fica mais inteligente gratuitamente.

Possua-o — MIT, BYOK, local-first

Use-o em qualquer lugar, incorpore-o em qualquer coisa — sem amarras de copyleft, sem necessidade de revisão legal. Suas habilidades, rastreamentos e registros de execução são seus dados — sair é copiar uma pasta. Os formatos são especificados em SPEC.md, uma referência normativa estilo RFC para que qualquer um possa emiti-los ou consumi-los sem ler o código-fonte.

Contribuindo

Issues e PRs são bem-vindos — veja SPEC.md para os formatos (a especificação prevalece sobre o código; corrija o código, não a especificação). npm test executa a suíte completa; npm run build && npx tsc --noEmit antes de um PR.

git clone https://github.com/seldonframe/reelier && cd reelier
npm install && npm test

Histórico de estrelas

Licença

MIT — livre para bifurcar, incorporar, auditar e auto-hospedar para sempre. (Versões ≤0.16.0 foram lançadas sob AGPL-3.0 e assim permanecem.)