CodeClone

---

[!IMPORTANT] Seções marcadas com 2.1 alpha exigem o pré-lançamento do CodeClone 2.1. Todo o restante funciona com a versão estável atual, CodeClone 2.0.2.

O que é o CodeClone?

O CodeClone ajuda desenvolvedores a usar agentes de IA para codificação sem perder o controle sobre mudanças estruturais.

Antes de um agente editar código, o CodeClone registra a mudança pretendida, mapeia o raio de impacto estrutural e estabelece limites explícitos de edição. Após a edição, ele compara o patch real com o escopo declarado, verifica regressões estruturais e deixa um recibo de revisão auditável.

O CodeClone não gera nem reescreve arquivos-fonte, e não pede a um LLM que decida se uma mudança estrutural é segura. Cada descoberta e cada bloqueio vêm de fatos determinísticos do repositório compartilhados entre agentes, revisores humanos, IDEs, relatórios e CI.

Capacidade	O que oferece
Análise estrutural canônica	Um relatório determinístico: clones, complexidade, acoplamento, coesão, código morto, mapa de módulos, inventário de API, junções de cobertura
Governança ciente de baseline	Registra dívida legada aceita e a separa de regressões introduzidas pela mudança atual
Um relatório, várias superfícies	CLI, HTML, JSON, Markdown, SARIF, MCP, integrações com IDE e GitHub Actions a partir de um único payload canônico
Controlador de Mudanças Estruturais — 2.1 alpha	Controle de mudança orientado a intenção, raio de impacto, limites explícitos de edição, verificação de patch e recibos de revisão
Contexto de Implementação ao Vivo — 2.1 alpha	Contexto estrutural e de grafo de chamadas em tempo real servido a partir da execução de análise atual — sem índice obsoleto para manter
Memória de Engenharia — 2.1 alpha	Conhecimento local, tipado e vinculado a evidências do projeto, além de históricos reutilizáveis de mudanças controladas anteriores
Coordenação de agentes — 2.1 alpha	Intenções multiagente seguras contra conflitos, filas, recuperação e higiene do espaço de trabalho

O CodeClone não exige serviço hospedado nem conta em nuvem. Estado de análise, estado do controlador, Memória de Engenharia e trajetórias são armazenados localmente.

Por que a intenção vem antes do diff

A maioria das ferramentas de revisão começa depois que o patch já existe. O CodeClone começa antes:

task request
  → declared intent
  → structural blast radius
  → explicit boundary
  → actual patch
  → deterministic verification

A expansão do escopo do agente pode parecer razoável no diff final. Uma tarefa estreita pode se espalhar silenciosamente para helpers compartilhados, testes, configuração, APIs públicas ou módulos não relacionados.

Quando essa expansão chega ao diff final, ela já parece intencional. O CodeClone a detecta no limite declarado — comparando o que o agente disse que mudaria com o que realmente mudou.

Início rápido

Requer Python 3.10 ou mais recente.

1. Analise um repositório

Execute a versão estável sem instalar nada:

uvx codeclone@latest .

Prefere um relatório navegável? Gere a visualização em HTML e abra-a:

uvx codeclone@latest . --html --open-html-report

Depois que você usar regularmente, instale-o como ferramenta local:

uv tool install codeclone
codeclone .

2. Registre o baseline estrutural atual

Antes de pedir a um agente que altere o repositório, capture o estado aceito uma vez:

codeclone . --update-baseline
git add codeclone.baseline.json
git commit -m "chore: add CodeClone structural baseline"

O baseline registra a dívida estrutural que já existe. A análise futura pode então separar novas regressões das descobertas que já estavam presentes, para que agentes e revisores possam focar no que a mudança atual introduziu.

Atualizar o baseline é uma ação explícita de governança. Não o regenere apenas para fazer uma verificação que falha passar.

3. Conecte seu agente de IA — 2.1 alpha

Continue para Controle de mudança de agente abaixo para instalar a superfície de controle MCP e conectar o CodeClone ao Claude Code, Cursor, VS Code, Codex ou Claude Desktop.

Um relatório estrutural canônico

O CodeClone executa uma análise determinística e renderiza o mesmo relatório canônico em todas as superfícies suportadas.

O relatório cobre:

• clones de função, bloco e segmento;
• deriva de clones e famílias de ramos duplicados;
• complexidade, acoplamento, coesão, ciclos de dependência e código morto;
• Mapa de Módulos — um grafo de dependências de pacotes/módulos com visualizações de ciclo, hub, módulo sobrecarregado e candidatos a desenrolamento;
• Revisão Guiada de Descobertas — uma fila de revisão priorizada com cartões de descoberta compartilhados, filtros e acompanhamento de progresso;
• inventário de API pública e detecção de quebras de API ciente de baseline;
• cobertura externa unida a pontos críticos estruturais;
• saúde estrutural determinística e prioridades de revisão.

codeclone . --json --html --md --sarif --text

Como o CodeClone funciona · Contrato do relatório canônico

Governança ciente de baseline e CI

O baseline é um contrato versionado e com integridade verificada que registra o estado estrutural aceito do repositório.

Ele permite que o CodeClone e agentes conectados distingam:

• descobertas que já existiam;
• regressões introduzidas pela mudança atual;
• atualizações deliberadas de baseline aprovadas pelo usuário.

Verifique mudanças futuras contra o baseline confirmado:

codeclone . --ci

Use o CodeClone no GitHub Actions:

- uses: orenlab/codeclone/.github/actions/codeclone@v2
  with:
    fail-on-new: "true"
    sarif: "true"
    pr-comment: "true"

O CI pode rejeitar clones recém-introduzidos, regressões de métricas, quebras de API e regressões de cobertura sem exigir que o repositório existente esteja limpo primeiro.

Contrato de baseline · Integração com CI e portões de qualidade

Como o CodeClone difere

Linters verificam estilo e correção arquivo por arquivo. Detectores de clones relatam duplicação e param por aí. Bots de revisão hospedados pedem a um modelo uma opinião sobre um diff finalizado.

O CodeClone combina detecção de clones baseada em CFG, governança de baseline multi-métrica e uma superfície de controle MCP somente leitura em um único pacote local-first e de código aberto — e os aplica antes da edição acontecer, não apenas depois. Fatos estruturais são calculados deterministicamente, então a mesma entrada sempre produz o mesmo veredito, no terminal, no CI e dentro do loop do seu agente.

Controle de mudança de agente — 2.1 alpha

Instale a superfície de controle MCP

uv tool install --prerelease allow "codeclone[mcp]"
codeclone-mcp --transport stdio

O servidor expõe 38 ferramentas MCP cobrindo análise, controle de mudança, raio de impacto, memória e diagnósticos. As respostas são construídas para loops de agente: orientação determinística next_tool, payloads cientes de orçamento de tokens e respostas que mantêm fatos de controle obrigatórios inline enquanto vinculam evidências completas para aprofundamento.

Antes de bloquear agentes ou CI, confirme [tool.codeclone] e a higiene local do gitignore:

codeclone setup status
codeclone setup plan
codeclone setup apply   # or: codeclone setup wizard

Veja Configuração e prontidão do repositório.

Conecte-o ao seu cliente

Cliente	Configuração
VS Code	Configuração da extensão
Cursor	Plugin e habilidades
Claude Code	Configuração do plugin
Codex	Configuração do plugin
Claude Desktop	Configuração do pacote

Todo cliente usa a mesma interface MCP e os mesmos fatos estruturais canônicos.

O fluxo de trabalho de mudança controlada

Para um agente, o fluxo de trabalho normal é:

analyze → start → edit → finish

Analisar. O CodeClone constrói um relatório estrutural canônico para o repositório e o compara com o baseline aceito.

Iniciar. start_controlled_change:

• registra a intenção do agente;
• mapeia o raio de impacto estrutural;
• separa caminhos editáveis do contexto de revisão e limites de não tocar;
• expõe o orçamento de regressão relativo ao baseline aceito;
• retorna o resultado autoritativo de edit_allowed.

Editar. O agente escreve o código. O CodeClone não gera nem reescreve arquivos-fonte. Onde o host suporta hooks, as integrações podem impedir edições a menos que edit_allowed=true. Durante a edição, o agente permanece orientado por meio do Contexto de Implementação ao Vivo em vez de redescobrir o repositório com buscas amplas.

Finalizar. finish_controlled_change:

• resolve os arquivos realmente alterados;
• verifica o escopo declarado contra o patch real;
• verifica mudanças estruturais;
• valida alegações opcionais de revisão;
• registra evidências do Patch Trail;
• produz um recibo de revisão auditável.

Se o patch cruzar o limite declarado ou introduzir regressões além do orçamento, a verificação falha — e o recibo registra exatamente onde e por quê. O resultado não é uma opinião de IA sobre o patch. É uma comparação determinística entre intenção declarada, estrutura do repositório, baseline aceito e mudança real.

Leia o guia do Controlador de Mudanças Estruturais

Contexto de Implementação ao Vivo

get_implementation_context serve ao agente contexto limitado e com escopo de tarefa diretamente da execução de análise atual:

• contexto estrutural e relações de chamadas para o escopo de edição declarado;
• mapas de verdade orientados a contrato e âncoras de teste;
• sinais de atualização e limites de intenção ativos.

Não há banco de dados vetorial separado se afastando do código, nem daemon de observação reindexando a árvore. O contexto vem da mesma análise que produz descobertas e bloqueios — então o que o agente lê é o que o verificador verificará. O contexto é somente leitura: informa edições, mas nunca as autoriza.

Também na linha 2.1

• Observabilidade de Plataforma — rastreamento em tempo de desenvolvimento de CLI, MCP, fases de análise, atividade de banco de dados e pressão de payload, para que você possa ver o que o próprio CodeClone está fazendo e quanto custa.
• Análise de Corpus — agrupamento offline de intenções e interpretabilidade sobre mudanças controladas registradas, com perfis versionados e saídas JSON/HTML inspecionáveis.

Memória de Engenharia — 2.1 alpha

A Memória de Engenharia dá aos agentes contexto durável e específico do repositório sem tratar a saída do modelo como verdade do projeto.

O armazenamento local SQLite pode conter:

• notas de arquitetura e contrato;
• riscos, âncoras de teste e superfícies públicas;
• proveniência de git e controle de mudança;
• trajetórias anteriores e evidências do Patch Trail;
• padrões consultivos recorrentes chamados Experiências.

Registros criados por agentes permanecem como rascunhos até que um humano os aprove.

codeclone memory init --root .
codeclone memory search "baseline schema" --match all

A recuperação é híbrida — busca lexical FTS5/BM25, busca vetorial opcional via LanceDB e Fusão de Rank Recíproco combinando as duas — com ranqueamento totalmente reproduzível.

A memória pode orientar um agente. Ela não pode autorizar edições, substituir o raio de explosão, alterar um portão ou substituir fatos canônicos de relatórios.

Documentação de Memória de Engenharia · Trajetórias e Experiências

Limites de confiança

• Descobertas estruturais e portões vêm de análise determinística, não de julgamento de LLM.
• edit_allowed é um resultado explícito do controlador; status ou propriedade de aconselhamento não concede permissão.
• Comandos de análise somente leitura não modificam código-fonte ou estado de governança do projeto.
• Atualizações de linha de base são ações explícitas de governança aprovadas pelo usuário.
• Operações do controlador e da memória gravam apenas em seus armazenamentos de estado locais explícitos.
• Evidências de memória, trajetória e contexto de implementação permanecem apenas consultivas.
• stdio é o transporte recomendado para clientes locais.
• Exposição HTTP remota requer --allow-remote explícito.

Contribuindo

Relatórios de bugs, discussões de recursos e pull requests são bem-vindos — comece com Issues ou Discussões, ou entre no Discord.

Execute a versão do repositório a partir do código-fonte:

git clone https://github.com/orenlab/codeclone.git
cd codeclone
uv sync --all-extras
uv run codeclone .

Documentação

orenlab.github.io/codeclone

• Começando
• Controlador de Mudança Estrutural
• Memória de Engenharia
• Uso do MCP
• Referência de configuração

Licença

• Código: MPL-2.0
• Documentação: MIT

Consulte LICENSES.md para o mapa de escopo de licenças.

Links

• PyPI: https://pypi.org/project/codeclone/
• Discord: https://discord.com/invite/U72KmRvpUx
• Issues: https://github.com/orenlab/codeclone/issues
• Discussões: https://github.com/orenlab/codeclone/discussions