I have been writing about CodeClone 2.0 in public while the beta line was still moving.

It started with the baseline-aware code health model, then moved into the budget-aware MCP server for AI agents, the review surfaces for VS Code, Claude Desktop, and Codex, and finally Coverage Join: the part where structural findings learn what your tests actually cover.

Now CodeClone 2.0.0 is stable.

This post is not a full feature dump. It is the final story of what the 2.0 line became.

The short version:

Agents make code cheaper to produce. CodeClone makes structural regressions harder to ship.

That is the niche I care about.

CodeClone is a deterministic structural review layer for Python projects. It separates accepted debt from new regressions, produces one canonical report, and exposes that same truth through CLI, HTML, GitHub Actions, VS Code, Claude Desktop, Codex, and MCP.

Why this matters more now

AI coding tools are getting better fast.

That changes the shape of engineering work.

The hard part is not always writing the next function. The hard part is keeping a repository governable while code is produced faster than before.

The failure mode is usually not dramatic.

It looks more like this:

• one more duplicated branch of business logic;
• one more helper that overlaps with three existing helpers;
• one more large module that becomes the place where everything changes;
• one more public API change that nobody noticed in review;
• one more risky function that is not actually measured by coverage;
• one more agent run that spends context on low-value noise.

Each individual change can look reasonable.

The repository still gets worse.

That is where structural review becomes useful.

The core idea: accepted debt vs new regressions

The most important part of CodeClone is still the baseline model.

A mature repository usually has historical debt. If a tool says “you have 700 problems,” the team will probably do one of three things:

1. ignore it;
2. disable it;
3. spend weeks fighting history instead of reviewing the current change.

CodeClone uses a different model:

uv tool install codeclone

codeclone . --update-baseline
codeclone . --ci

The baseline says: this is the state we already accepted.

Future runs can then separate:

• known debt;
• new regressions.

That changes CI from “please fix the entire past” into a much more useful question:

Did this branch make the repository structurally worse than the trusted baseline?

That is the difference between a noisy report and a governance workflow.

The baseline is not just a JSON convenience file. It is a contract with schema versioning, fingerprint version, Python tag compatibility, and integrity checks. If the baseline is not trusted, CI should not pretend everything is fine.

One analysis, many surfaces

One of the strongest design rules in CodeClone 2.0 is simple:

The analysis is one thing. Everything else is a projection.

The CLI, HTML report, JSON, Markdown, text, SARIF, MCP server, VS Code extension, Claude Desktop bundle, Codex plugin, and GitHub Action are not allowed to invent their own truth.

They all sit on top of the same canonical report model.

That matters because the user should not see one thing in CI, another thing in the HTML report, and a third thing through MCP.

It also matters for agents.

A coding agent should not need to guess whether MCP results are “kind of similar” to CLI results. The MCP layer is a read-only control surface over the same deterministic analysis.

MCP is not just tool access

I think a lot of MCP integrations make the same mistake: they expose a pile of tools and leave the agent to figure out the workflow.

That is technically useful, but it is not enough.

Agents need shape.

If the cheapest useful path is not obvious, the model will often over-fetch, enumerate too early, and burn context on low-value details.

CodeClone MCP is designed around a triage-first path:

1. analyze the repository or changed scope;
2. read the summary or production triage;
3. inspect hotspots or focused checks;
4. open one finding;
5. request remediation context only after selecting a concrete issue.

This is the important part:

CodeClone MCP is a control surface, not a report dump.

It is read-only by design. It does not modify source files. It does not update baselines. It does not write a separate source of truth. It requires absolute repository roots so the client does not accidentally analyze the wrong directory.

That sounds strict, but for agentic workflows strictness is useful.

A good agent tool should not only answer questions. It should reduce the chance that the agent asks the expensive or misleading question first.

help(topic=...) became more important than I expected

One small MCP feature ended up being surprisingly important: bounded help.

CodeClone MCP includes help(topic=...) for topics such as:

• workflow;
• baseline semantics;
• latest run behavior;
• review state;
• changed-scope routing;
• suppressions;
• analysis profile;
• coverage.

This is not documentation dumping. It is a small uncertainty-recovery tool.

When an agent is unsure what a surface means, it can ask a bounded question instead of going straight into broad enumeration.

That changed the feel of the interface.

The server became less like “here are 21 tools” and more like “here is a route through structural review.”

Coverage Join: structural risk needs test context

One of the features I care about most in 2.0 is Coverage Join.

Coverage alone is useful, but it is often too coarse.

A project can have a high overall coverage percentage while a specific risky function is either under-tested or missing from the coverage scope entirely.

CodeClone joins Cobertura XML coverage data with its own per-function structural facts:

codeclone . --coverage coverage.xml --fail-on-untested-hotspots --coverage-min 50

The important detail is that CodeClone keeps two situations separate:

• a measured function is below the configured coverage threshold;
• a function exists in CodeClone analysis but is missing from the supplied coverage.xml scope.

Those are different review situations.

“Poorly covered” and “not measured by this coverage file” should not be collapsed into the same message.

For CI, this enables a practical gate:

if structurally risky code is under-tested or outside coverage scope, review it before merge.

For agents, it gives better context:

not just “this function is complex,” but “this function is complex and the test signal is weak or missing.”

Security Surfaces: not SAST, not vulnerability claims

Another new layer in 2.0 is Security Surfaces.

This is the easiest one to explain badly, so I want to be explicit.

CodeClone is not a security scanner.

Instead, Security Surfaces is a report-only inventory of security-relevant capability boundaries.

Examples include:

• process execution;
• dynamic execution;
• dynamic imports;
• deserialization;
• filesystem mutation;
• crypto and integrity primitives;
• auth/session/token/secret-related code;
• network boundaries.

Why is that useful?

Because during review, it matters whether a change touches boundary code.

Especially when that boundary also intersects with:

• high complexity;
• low coverage;
• overloaded modules;
• clone drift;
• public API changes.

Security Surfaces is not a red alarm.

It is a map of sensitive places that deserve better review context.

Dependency depth: I removed the magic number

Earlier in the 2.0 line, dependency depth used a fixed threshold.

That was too blunt.

A small package and a larger tool with CLI, MCP, HTML reports, IDE integration, and GitHub Action surfaces should not be judged by the same hard-coded chain length.

So the final 2.0 model moved to an adaptive dependency-depth profile:

• average depth;
• p95 depth;
• max depth;
• longest chains;
• cycles.

Cycles remain a hard structural signal.

Acyclic depth is now treated as project-relative pressure rather than a universal failure condition.

This is a good example of how I want CodeClone to evolve: if a metric starts looking precise but unfair, the contract should change instead of forcing reality to match a pretty number.

API Surface and Adoption

CodeClone 2.0 also added two related review layers: API Surface and Adoption.

API Surface tracks public symbols and compares them against a trusted metrics baseline when enabled.

That makes it easier to notice:

• newly public symbols;
• removed symbols;
• breaking changes;
• public surface drift.

Adoption tracks presence, not quality:

• parameter annotations;
• return annotations;
• public docstrings;
• explicit Any counts.

This is intentionally not “typing quality.”

A project can have annotations and still have weak type design. But for teams migrating incrementally, presence coverage is still a useful governance signal:

did this branch make the public surface less typed or less documented than before?

That is the kind of question CI can answer honestly.

Overloaded Modules

CodeClone also reports overloaded modules.

This is report-only. It is not a gate.

The point is not to say “this file is bad.” The point is to rank modules where several kinds of pressure meet:

• size;
• complexity;
• coupling;
• responsibility concentration;
• participation in other signals.

In larger repositories, this helps answer a practical question:

If I want to improve the project without guessing, where should I start?

That is often more useful than looking only at the single function with the highest cyclomatic complexity.

Native surfaces: VS Code, Claude Desktop, Codex

CodeClone 2.0 is no longer only a CLI tool.

It now has native or local integration surfaces around the same MCP server.

VS Code

The VS Code extension is a native MCP client for CodeClone.

It can show triage-first review data, jump to source, display supported Coverage Join and Security Surfaces facts, respect workspace trust, and avoid sending code anywhere.

It does not reimplement analysis.

It talks to the local codeclone-mcp.

Marketplace:

https://marketplace.visualstudio.com/items?itemName=orenlab.codeclone

Claude Desktop

The Claude Desktop bundle is an .mcpb wrapper around the local codeclone-mcp launcher.

It is not a second server. It is an installation and configuration surface.

Codex

The Codex plugin provides local discovery metadata, MCP configuration, and review skills. Again, the goal is not to build a separate analyzer, but to guide the agent through the correct CodeClone workflow.

GitHub Action

For CI and pull requests, CodeClone ships a composite GitHub Action:

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

It can:

• run baseline-aware checks;
• generate JSON and SARIF;
• upload SARIF to GitHub Code Scanning;
• publish a PR summary comment;
• keep review logic out of the project’s workflow scripts.

That is the kind of surface I want CodeClone to have: useful in local development, useful in CI, and useful for agents — without each integration inventing its own interpretation.

What “stable” means here

2.0.0 does not mean the project is done.

It means the main 2.0 contract is stable enough to stop treating it as a prerelease.

The important parts are now established:

• uv tool install codeclone works without --pre;
• codeclone[mcp] is the normal optional extra for MCP;
• CLI, report, baseline, cache, metrics baseline, and MCP semantics are documented;
• integrations are aligned with the final 2.0 package;
• legacy shim paths are gone;
• runtime compatibility issues are surfaced explicitly instead of being hidden.

The limitations are also part of the contract:

• CodeClone does not replace linters;
• CodeClone does not replace tests;
• Security Surfaces does not replace SAST;
• Coverage Join does not replace coverage.py;
• MCP does not mutate repositories;
• HTML and IDE clients do not create a second truth.

That matters.

A quality tool loses trust quickly when it promises more than it can prove.

Try it

Minimal install:

uv tool install codeclone
codeclone .
codeclone . --html --open-html-report

Baseline-aware CI flow:

codeclone . --update-baseline
codeclone . --ci

MCP for local agents and IDEs:

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

Coverage Join:

codeclone . --coverage coverage.xml --fail-on-untested-hotspots

Useful links:

• GitHub: https://github.com/orenlab/codeclone
• PyPI: https://pypi.org/project/codeclone/
• Docs: https://orenlab.github.io/codeclone/
• Live HTML report: https://orenlab.github.io/codeclone/examples/report/
• VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=orenlab.codeclone

What comes next

2.0 is a stable foundation, not the end.

The next things I care about most are:

• better changed-scope review for pull requests;
• evolving Security Surfaces into a more useful but still honest pressure signal;
• improving GitHub Action and marketplace flows;
• making native clients smoother;
• testing CodeClone on more large Python repositories.

If you try CodeClone on your own project, I am especially interested in the uncomfortable feedback:

• where the signal feels noisy;
• where the tool is too conservative;
• where the report needs more context;
• which MCP workflows actually help an agent;
• which CI gates you would want to tune differently.

CodeClone started as a structural clone detector.

Version 2.0 turns it into a structural review layer for Python teams that care about CI, IDE workflows, and agent-assisted development.

The principle is still the same:

do not pretend to know more than the analysis can prove; make the facts, boundaries, and regressions clear enough for a human or an agent to review.

Agents make code cheaper to produce.

Tools like CodeClone should make structural regressions harder to ship.