DEV Community: orenlab

Structural review that finally knows what your tests cover

orenlab — Thu, 16 Apr 2026 13:52:28 +0000

In earlier posts, I wrote about why I built CodeClone, why I exposed it through MCP for AI agents, and how b4 turned it into a real review surface for VS Code, Claude Desktop, and Codex.

b5 is the release where structural review stops being a parallel universe to your test suite.

Until now, CodeClone could tell you that a function is long, complex, duplicated, or coupled to everything — but it had no idea whether that function was covered by a single unit test. That mattered more than I wanted to admit. A complex function with a 0.98 coverage ratio is not the same risk as the identical function with 0.0. A reviewer knows this. An AI agent reading an MCP response doesn't — unless the tool tells it.

So b5 fixes that, and while doing it, also lifts a few other things that kept getting in the way:

typing and docstring coverage as first-class review facts
public API drift as a baseline-governed signal
intentionally-duplicated test fixtures stop polluting health and CI gates
a much clearer triage story for MCP and IDE clients
a rebuilt HTML report with unified filters and cleaner empty states
a Claude Desktop launcher that actually picks the right Python
a warm-path benchmark that now tells the truth

Let me walk through what changed and why.

1. Bring your `coverage.xml` into the review

The headline feature of b5 is Coverage Join. Point CodeClone at any Cobertura XML produced by coverage.py, pytest-cov, or your CI and it fuses test coverage into the same run that produces clone groups, complexity, cohesion, and dead code:

codeclone . --coverage coverage.xml --coverage-min 50 --html

What comes out is not "new coverage tool, please delete the old one." It's coverage used as a modifier on structural review:

Each function in the current run gets a factual coverage ratio.
Functions below the threshold show up as coverage hotspots with their complexity and caller count alongside.
High-risk findings can now read "complex + uncovered + new vs baseline" instead of just "complex."
A new gate, --fail-on-untested-hotspots, fails CI on below-threshold functions only where the coverage report actually measured them.

That last distinction is the part I care about most.

2. Honest about scope: measured vs out-of-scope

The easy mistake when bolting coverage onto a second tool is to silently treat "function missing from coverage.xml" as "function is uncovered." It makes the dashboard look busier, but it's a lie — the function might be covered by a coverage run that was filtered to a different package, or it might be a module the coverage config excluded on purpose.

b5 keeps these two cases cleanly separate:

Coverage hotspots — code that coverage.xml measured and reported below threshold. This is a hard signal.
Coverage scope gaps — code present in your repo but not in the coverage XML at all. This is a scoping observation, not a verdict.

Both show up in the report and through MCP, but with different meanings. In mixed monorepos this stops being cosmetic very fast.

None of this changes clone identity, fingerprints, or NEW-vs-KNOWN semantics — the baseline model is untouched. Coverage Join is a current-run fact, not baseline truth.

3. Typing and docstring coverage are now part of the picture

I used to expose "typing coverage" and "docstring coverage" as optional toggles. In practice, nobody turned them on, and they kept hiding behind flags that felt vestigial.

b5 removes the toggles and just collects adoption coverage whenever you run in metrics mode:

parameter annotation coverage
return annotation coverage
public docstring coverage
explicit Any count

They land in the main CLI Metrics block, in the HTML Overview, in MCP summaries, and in the baseline. And they get their own CI gates:

codeclone . \
  --min-typing-coverage 80 \
  --min-docstring-coverage 60 \
  --fail-on-typing-regression \
  --fail-on-docstring-regression

The regression gates are the interesting pair: they don't force you to reach a specific threshold, they just fail CI when adoption drops compared to your trusted baseline. That tends to be more realistic for real codebases where you're migrating gradually.

4. Public API drift becomes a first-class signal

Another thing that used to live outside the review surface: "did this PR break the public API?"

b5 adds an opt-in API Surface layer that takes a snapshot of your public symbols — modules, classes, functions, their parameters and return types — into the metrics baseline. Subsequent runs produce a baseline diff with explicit categories: additions, breaking changes, everything else.

# Record the snapshot
codeclone . --api-surface --update-metrics-baseline

# Guard PRs
codeclone . --fail-on-api-break

It's not a type checker and it's not SemVer enforcement. It's "the set of externally-callable names in this package just changed in a way that is likely to break downstream users, please confirm." For libraries that's the thing you want CI to block on.

Private symbols are classified separately from public ones, so moving an internal helper around doesn't pollute the diff.

5. Golden fixtures stop showing up as debt

Some repositories — including CodeClone itself — intentionally keep duplicated golden fixtures to lock report contracts and parser behavior. Those clones are real. They are also not live review debt.

b5 adds a project-level policy for exactly that case:

[tool.codeclone]
golden_fixture_paths = ["tests/fixtures/golden_*"]

Clone groups fully contained in those paths are:

excluded from the health score
excluded from CI gates
excluded from active findings
still carried in the report as suppressed facts

So the tool stays honest — you can still see the suppressed groups in the HTML Clones tab and in the canonical JSON — without making CI noisier than it needs to be. If a group stops being "fully inside the fixture paths," it stops being suppressed automatically.

6. Triage that says what it's actually looking at

MCP summary and triage payloads in b5 include a few compact interpretation fields that turned out to matter a lot for both AI agents and humans:

health_scope — is this number repository-wide, production-only, or for a specific focus?
focus — what does "new findings" actually mean for this run?
new_by_source_kind — of the new findings, how many are in production code vs tests vs tooling?

The net effect is that an agent asking "is this PR risky?" no longer has to guess whether "3 new findings" means "three new bugs in production" or "three new flake-prone tests." The payload tells it directly. The VS Code extension uses the same fields to explain repository-wide health, production focus, and outside-focus debt without widening the review flow.

The extension also now surfaces Coverage Join facts in its overview when the connected server supports them, and the optional in-IDE help topics are gated by server version so they stay honest about what's actually available.

7. The HTML report got a proper rebuild

b4 made the HTML report useful. b5 makes it feel finished.

Unified filters popover — Clones and Suggestions share the same filter UX: one button, one menu, an active-filter count, keyboard dismiss. Every control lives in the same place on every tab that has filters. No more two-row filter strips that wrap on narrow screens.
Cleaner empty states — instead of empty tables, sections with no findings now render a single reassuring row with an explicit "no issues detected" message and an icon. Silence has meaning now.
Coverage Join subtab — Quality gets a dedicated Coverage Join view with per-function rows: coverage %, complexity, callers, source kind, and a clear marker for scope gaps.
Adaptive theme toggle — the theme button shows a sun in light mode and a moon in dark mode, resolved at paint time so you don't flash the wrong icon on first load.
Refreshed palette — the whole report moved to a chromatic neutral scale tinted toward the brand indigo, so surfaces, borders, and text live on the same hue axis instead of looking like "grayscale + one purple button."
Better provenance — the meta block makes it explicit which python tag the baseline was built for, and calls out baseline mismatches instead of hiding them.
Stat-card rhythm — KPI cards across Overview, Quality, Dependencies, and Dead Code share one card component now. Same padding, same typography, same tone variants.

None of that changes a single report contract. It's pure render-layer work.

8. Claude Desktop launches the right Python

A boring but high-impact b5 change: the Claude Desktop bundle now resolves your project's runtime before falling back to a global one. Poetry's .venv, workspace .venv, and an explicit workspace_root override all come before anything on PATH.

Before: installing CodeClone into your project, then launching it via Claude Desktop, would often run some other CodeClone from /usr/local/bin because that happened to be first on PATH. That's fixed.

If you've been getting subtly wrong results through Claude Desktop and couldn't explain why, this is the one to pull.

9. Safer and more deterministic under the hood

Two changes that are unglamorous but worth noting:

Git diff ref validation. When you use --diff-against, the supplied revision is now validated as a safe single-revision expression before being passed to git. No shell surprises, no accidental multi-ref expressions.
Canonical segment digests. Segment clone digests no longer use repr() — they're computed from canonical JSON bytes. This closes a subtle determinism hole where two runs on different interpreters could, in rare cases, produce different segment digests for the same input.

Neither changes clone identity or fingerprint semantics.

10. The warm path is actually warm

One of the more satisfying b5 fixes wasn't a feature at all.

I'd been quietly suspicious of the benchmark numbers for a while — warm runs were looking too good, and I couldn't make the shape of the curve match what the pipeline was actually doing. Turns out the benchmark harness had a bug that broke process-pool execution on warm runs, so the cache was being credited for work it wasn't doing.

After fixing the harness and tightening gating around benchmark runs so repo quality gates don't interfere, the numbers are now both fast and trustworthy. From the Linux smoke benchmark:

cold_full: 6.58s
warm_full: 0.95s
warm_clones_only: 0.86s

About 6.9× speedup on warm runs. The cache is no longer "probably helping" — it is clearly doing useful work, and now I can say that with a straight face.

Wrapping up

If b4 made CodeClone a real review surface, b5 is the release where that surface learned to ask useful second-order questions:

Is this complex function actually tested?
Is this low-coverage number a hard signal or a scope gap?
Is this new finding in production code or in fixtures?
Did this PR break the public API?
Is this duplication intentional test scaffolding or real debt?

Every one of those used to require me to eyeball two dashboards and a coverage report. Now there's a single canonical answer, and it ships consistently through CLI, HTML, JSON, SARIF, MCP, the VS Code extension, the Claude Desktop bundle, and the Codex plugin.

Try it

# Base install
uv tool install --pre codeclone

# With MCP for AI agents (Claude Desktop, Codex, VS Code, Cursor, ...)
uv tool install --pre "codeclone[mcp]"

A one-liner to feel the new shape on your own repo:

codeclone . \
  --coverage coverage.xml --coverage-min 70 \
  --min-typing-coverage 80 --fail-on-typing-regression \
  --api-surface --fail-on-api-break \
  --html

Open the HTML report, watch the Coverage Join tab populate, and check whether your "risky" functions really were the risky ones.

Feedback, issues, and PRs welcome on GitHub.

CodeClone b4: from CLI tool to a real review surface for VS Code, Claude Desktop, and Codex

orenlab — Sun, 05 Apr 2026 18:28:09 +0000

I already wrote about why I built CodeClone and why I cared about baseline-aware code health.

Then I wrote about turning it into a read-only, budget-aware MCP server for AI agents.

This post is about what changed in 2.0.0b4.

The short version: if b3 made CodeClone usable through MCP, b4 made it feel like a product.

Not because I added more analysis magic or built a separate "AI mode." But because I pushed the same structural truth into the places where people and agents actually work — VS Code, Claude Desktop, Codex — and tightened the contract between all of them.

A lot of developer tools are strong on analysis and weak on workflow. A lot of AI-facing tools shine in a demo and fall apart in daily use.

For b4, I wanted a tighter shape:

the CLI, HTML report, MCP, and IDE clients should agree on what "health" means
the first pass should stay conservative
deeper inspection should be explicit, not accidental
report-only signals should stay visible without polluting gates
setup failures should tell you what went wrong

That is the release theme. Not "more output" — better day-to-day workflows.

The most interesting new layer: Overloaded Modules

Clone detection tells you this logic is repeated. Complexity tells you this function is locally hard to reason about.

Overloaded Modules asks a different question: which modules are taking on too much responsibility?

The signals include module size pressure, dependency pressure, hub-like shape, and reimport-heavy structure. This points to code that often feels wrong before it is easy to classify. You know the file keeps attracting logic. Every change in it feels heavier than it should. But it is not a clone group or a single high-complexity function.

The important design choice: this layer is report-only for now. It shows up in JSON, HTML, Markdown, text, MCP, and the VS Code extension — but it does not affect health score, gates, baseline novelty, or SARIF.

I wanted the signal to be useful before letting it become consequential.

VS Code became a real client, not a demo

The preview VS Code extension is the first release where CodeClone feels properly usable inside an editor instead of only around one.

It is now live on the Visual Studio Marketplace.

The extension is not a generic linter panel. It is built around a review loop:

Analyze the workspace.
Look at compact structural health.
Review priorities first.
Reveal source.
Open detail only when needed.

A lot of extensions get this wrong by dumping every result into the IDE and calling it integration. I wanted the opposite: a client that is baseline-aware, triage-first, source-first, trust-aware, and read-only.

b4 also tightened the surrounding UX:

Restricted Mode — onboarding works in untrusted workspaces, but analysis stays gated until trust is granted
Explicit analysis profiles — "deeper review" is a deliberate follow-up, not silent threshold drift
Hard version checks — if the IDE client quietly talks to the wrong local server version, you do not get a tool you can trust; you get folklore

That last one mattered more than I expected.

Claude Desktop and Codex speak the same contract

I also added native client paths for Claude Desktop and Codex.

The goal was not "be available in more places." It was keeping one analysis contract across all of them:

no second analyzer
no plugin-specific findings
no AI-only semantics
no client that quietly disagrees with the CLI

Claude Desktop gets a local .mcpb bundle with pre-loaded review instructions.
Codex gets a native plugin with two focused skills — full review and quick hotspot discovery. Both sit on top of the same codeclone-mcp server.

That may sound boring, but boring is good here. The more clients you add, the easier it becomes to fork your own semantics without noticing. A lot of the b4 work was about resisting exactly that.

Conservative first, deeper only when you mean it

CodeClone defaults are intentionally conservative. That is the right first pass for CI, baseline-aware review, and agent-driven workflows.

But there is a real second need: sometimes the default pass looks clean, and you want to go hunting for smaller, more local repetition.

b4 makes that distinction explicit:

Start with defaults or pyproject.toml thresholds.
Use that as the stable first pass.
Lower thresholds only for an intentional deeper review.

This now shows up clearly in MCP help topics and in the VS Code analysis profiles.

"More sensitive" is not the same as "more correct." A clean conservative pass
does not prove there is no finer-grained repetition. But a lower-threshold exploratory pass should not quietly pretend to have the same meaning as the default profile. That distinction needed to become product-level.

MCP got smarter about guiding agents — and cheaper to talk to

Two things happened on the MCP side that are easy to miss but matter a lot in practice.

First: the help tool. In b3, agents had 20 analysis and query tools but no way to ask "what should I do next?" or "what does this baseline state mean?" without burning tokens on trial and error.

b4 adds a help(topic=...) tool with bounded, static answers for common uncertainty points: workflow sequencing, analysis profile semantics, baseline interpretation, suppression rules, review state, and changed-scope review. An agent can ask one cheap question instead of making three exploratory tool calls to figure out the right next step.

This is a small surface — seven topics, short answers, no dynamic analysis. But it changes the economics of agent workflows significantly. The difference between "the agent guesses and retries" and "the agent asks and proceeds" is often 3–5x in token cost.

Second: tighter token budgets across the board. b4 continued the budget-aware work from b3:

finding IDs are now sha256-based short forms instead of full canonical URIs
the derived section in MCP payloads is projected down to what agents actually need
metrics_detail is paginated with family and path filters so agents never pull the full metrics table by accident

None of this changes the canonical report — the JSON is still the complete truth. But the MCP view over it is now meaningfully leaner.

The boring fixes that matter most

Some of my favorite changes in b4 are not flashy:

setup guidance that matches the real install path
faster launcher failure behavior with clear error messages
stricter local version handling across all client surfaces
enriched MCP server instructions so agents get behavioral context on connect, not just a list of tools
terminology cleanup around module hotspots

This is not the kind of work that looks impressive in a screenshot. But it is exactly the kind of work that makes an engineering tool feel trustworthy over weeks and months.

What `b4` feels like

b1 — CodeClone became more than a clone detector.
b3 — it became a serious MCP server.
b4 — it started to feel coherent across the CLI, the report, MCP, and every client surface.

You can start in the editor. You can stay aligned with baseline-aware truth. You can inspect module-level pressure without turning it into fake gating. You can move between human and agent workflows without changing the underlying semantics.

That is much closer to what I wanted CodeClone to become.

Try it

uv tool install --pre codeclone        # core CLI (beta)
uv tool install --pre "codeclone[mcp]" # + MCP server for agents and IDEs
codeclone .                            # analyze the current project
codeclone . --html --open-html-report  # open the interactive report

GitHub — source, extensions, plugin
Docs — contracts, guides, live report
MCP guide — agent and IDE setup
PyPI

If you are building review workflows around IDEs, MCP clients, or AI-assisted refactoring, I would love feedback on one question:

What makes a structural analysis tool feel trustworthy once it leaves the CLI and starts living inside real developer workflows?

I turned my Python code quality tool into a budget-aware MCP server for AI agents

orenlab — Wed, 01 Apr 2026 13:00:50 +0000

I already wrote about why I built CodeClone and why I care about baseline-aware
code health:

I built a baseline-aware Python code health tool for CI and AI-assisted coding

This post is about what changed in 2.0.0b3.

The short version: this is the first release where CodeClone feels less like a Python structural analysis CLI and more like a serious MCP surface for AI coding agents.

Not by building a second engine.
Not by adding AI-specific heuristics to the core.
But by exposing the same deterministic, baseline-aware pipeline through a read-only MCP layer that agents can actually use.

Why MCP mattered for CodeClone

Once you start using coding agents seriously, the hard part is not "can the model write code?"

The harder questions are:

what changed structurally?
is this debt new or already accepted in baseline?
is this production risk or just test noise?
should this block CI?
what is the safest next refactor target?

That is the gap I wanted CodeClone to close.

What shipped in `2.0.0b3`

The headline is an optional MCP server:

pip install --pre "codeclone[mcp]"
codeclone-mcp --transport stdio

Since b3 is still a beta, the --pre flag matters here.

But the useful part is the workflow around it.

b3 adds three things that matter together:

a read-only MCP surface for agents and IDE clients
review-oriented workflows: changed-files analysis, run comparison, gate preview, and PR summaries
tighter surrounding surfaces: stronger SARIF, better HTML navigation, and directory hotspots

There is also a packaging change worth mentioning:

CodeClone source code is now under MPL-2.0
documentation stays under MIT

What makes this MCP layer different

I think there are a lot of tools now that can expose "some analysis" over MCP.

What I wanted from CodeClone was stricter than that.

1. Canonical-report-first

The MCP layer is not a second truth path.

It reads the same canonical report model as the CLI, HTML, and SARIF surfaces.
That means an agent is not looking at an "AI view" that quietly disagrees with what CI or the report says.

2. Read-only

This was non-negotiable for me.

CodeClone MCP does not mutate:

source files
baselines
repository state
on-disk report artifacts

The only mutable part is session-local review state, and that stays in memory only.

3. Budget-aware by design

This is the part I ended up caring about more than I expected.

A lot of MCP tools are technically useful, but easy to use badly. An agent can burn a lot of tokens just by listing too much too early.

CodeClone MCP is intentionally shaped so that the cheapest useful path is the default path.

It is not only bounded in payload shape. It actively guides agents toward low-cost, high-signal workflows.

The cheapest useful path is now the most obvious path.

The workflow I wanted agents to follow

The right first pass is not "dump all findings."

In practice, the first useful question is rarely “show me everything.”
It is usually “where should I look first?”

It is:

analyze_repository or analyze_changed_paths
→ get_run_summary or get_production_triage
→ list_hotspots or focused check_*
→ get_finding
→ get_remediation

That sounds simple, but it matters a lot.

It means:

cheap overview first
narrow triage second
deep detail only when it is actually needed

That is a better fit for LLMs, and honestly a better fit for humans too.

Real token cost on a dirty repository

I wanted to check whether this was just a nice theory, so I tested it on one of my own messier private Python repos.
It is still in an early development stage, is not public yet, and from CodeClone's point of view it currently has a lot of structural debt.
It works, but "works" and "structurally healthy" are obviously not the same thing.

In one local run, that looked like this:

449 Python files
108,939 lines
2,729 functions
1,048 classes
659 findings
health score 34 (F)

Then I compared two MCP paths.

Broad first-pass flow

A more naive "ask for a lot of things" practical cycle came out to about:

10,566 tokens

Guided first-pass flow

Following the new MCP guidance:

analyze_repository
get_production_triage
list_hotspots
get_finding
get_remediation

The same first-pass workflow came out to about:

2,535 tokens

That is roughly a 76% reduction in token cost for a useful first pass.

The payloads did not magically become tiny; the main change was that the MCP surface now guided the client toward a narrower first-pass workflow.

That result mattered to me because it changed how I think about MCP quality.

For agent tooling, payload size is only half the story.
The other half is whether the server nudges the agent toward the right path.

Why this matters for PR review

In practice, the most valuable agent loop is usually not “analyze the whole repository forever,” but “review what changed, compare it to baseline, and decide whether anything should block the merge.”

It is usually closer to:

code changed
tests passed
now check whether the structure got better or worse

That is why b3 puts a lot of weight on changed-scope review.

With CodeClone MCP, an agent can now ask things like:

what findings touch the files changed in this branch?
are these findings new relative to baseline?
what is the highest-priority structural issue here?
would this fail CI?
can I produce a short PR-ready summary?

That is a much better review loop than a giant flat findings dump.

What the MCP surface is good at now

The shape I like most is:

full repository analysis when you need canonical truth
changed-files analysis when you need review focus
compact triage first
single-finding drill-down second
markdown PR summary at the end

In practice, that makes prompts stay simple.

For example:

Changed-files review

Use CodeClone MCP to review the files changed in this branch.
Show me only findings that touch changed files, rank them by priority, and tell me whether anything here should block CI.

Safe refactor pick

Use CodeClone MCP to find one high-priority structural issue that looks safe to refactor. Explain why it is a good first target and what refactor shape you would use. Do not change code yet.

AI-generated code check

I added a lot of code with an AI agent.
Use CodeClone MCP to check for structural drift: new clone groups, duplicated branches, dead code, or design hotspots. Prioritize what is new relative to baseline.

That is the kind of MCP ergonomics I was aiming for: prompts stay fairly client-agnostic, and the server gives the agent a disciplined path.

`b3` is not only about MCP

Even though MCP is the headline, I did not want it to be isolated from the rest of the product.

2.0.0b3 also tightens the surrounding surfaces:

canonical report schema 2.2
cache schema 2.3
canonical design-finding thresholds recorded in report metadata
Hotspots by Directory in the HTML overview
stronger SARIF identities for code-scanning workflows
Composite GitHub Action v2 for CI and PR automation

That matters because I want all of these surfaces to agree:

CLI for CI
MCP for agents
HTML for navigation
SARIF for platform workflows

The product truth I am taking from this release

The biggest lesson from b3 is that a good MCP server is not just a pile of tools.

It is a control surface.

For CodeClone, that now means:

deterministic
canonical-report-first
read-only
budget-aware
triage-first
agent-guiding

That is the direction I want to keep pushing.

Not "AI magic."
Better control loops.

Try it (don't forget use `--pre`)

GitHub: orenlab/codeclone
Docs: orenlab.github.io/codeclone
MCP guide: orenlab.github.io/codeclone/mcp/
PyPI: pypi.org/project/codeclone

If you are already building with MCP clients, I would especially love feedback on one question:

what would make PR review through an MCP tool genuinely useful for your team?

I built a baseline-aware Python code health tool for CI and AI-assisted coding

orenlab — Thu, 26 Mar 2026 11:49:56 +0000

I built a baseline-aware Python code health tool for CI and AI-assisted coding

If you write Python with AI tools today, you’ve probably felt this already:

the code usually works, tests may pass, lint is green, but the structure gets worse in ways that are hard to notice
until the repository starts fighting back.

Not in one dramatic commit. More like this:

the same logic gets rewritten in slightly different ways across multiple files;
helper functions quietly grow until nobody wants to touch them;
coupling increases one import at a time;
framework callbacks look unused even when they are not;
dead code accumulates because generated code tends to leave leftovers behind.

That is the problem space I built CodeClone for.

CodeClone 2.0.0b1 is the first version where the tool really matches the model I wanted from the beginning: not just
“find some clones,” but track structural code health over time, in CI, with a trusted baseline.

This post is an introduction to that version and the design choices behind it.

First: I know the ecosystem is not empty

I’m not pretending this is the first serious tool in this space.

There are already strong tools around adjacent problems:

SonarQube / SonarCloud for broad code quality, governance, and quality gates
PMD CPD as one of the classic copy/paste detectors
jscpd for practical duplicate-code scanning across multiple languages
Vulture for Python dead-code detection
Radon / Xenon for complexity-related checks
and newer tools like pyscn, which also move toward structural/code-health analysis for Python

That matters, because I don’t think useful tools should be framed as “everything before this was wrong.”

CodeClone is not trying to replace all of the above.

Its angle is narrower and, I think, pretty specific:

structural duplication is a first-class signal;
baseline-aware governance is the center of the workflow, not an extra feature;
deterministic output is non-negotiable;
and the UI/report layer is not allowed to invent conclusions the analysis engine did not produce.

If I had to summarize the difference in one sentence, it would be this:

CodeClone is built around separating accepted debt from new regressions.

That sounds simple, but it changes the entire shape of the tool.

Why I think this matters more now

AI coding assistants are genuinely useful. I use them. They speed things up.

But they also change the failure mode of a codebase.

The biggest risk is often not “the AI wrote something syntactically invalid.” That part is easy to catch.

The harder problem is that AI tools are very good at producing locally plausible code:

one more handler,
one more service method,
one more variant of the same logic,
one more utility that overlaps with three existing ones.

Each individual change looks reasonable.

The repository as a whole gets worse.

That is why I think structural analysis is especially useful for AI-assisted teams. If you are using Claude Code,
Cursor, Codex, or similar tools, the important question is often not:

“Is this code valid?”

but:

“Did this change make the repository structurally worse?”

That is exactly the question a baseline-aware tool can answer well.

What CodeClone focuses on

At the core, CodeClone analyzes Python projects and looks at structural signals such as:

function clones
block clones
segment clones
structural findings like duplicated branch families
dead code
complexity
coupling
cohesion
dependency cycles
a combined health score

The outputs come in multiple formats:

HTML
JSON
Markdown
SARIF
Text

But they all come from a single canonical report document. That was important to me because I wanted consistency between
machine-readable outputs and the human-facing report.

The key idea: baseline-aware governance

This is the part I care about most.

A lot of code quality tools can tell you that your repository has problems. That is useful, but it is not enough for
real CI.

In a non-trivial codebase, there is usually historical debt:

old duplication
old complexity hotspots
old dead code
old architectural compromises

If a tool only says “you have 400 problems,” that doesn’t help much. Most teams will either ignore it or disable it.

CodeClone is designed around a different model:

take the current state as a baseline;
trust and validate that baseline explicitly;
keep accepted debt visible;
block new regressions.

That makes the tool much more usable in practice.

Instead of asking teams to become perfect overnight, it asks a much more realistic question:

“Did this branch make the codebase worse than the state we already accepted?”

That is the main reason I describe CodeClone as baseline-aware before I describe it as a clone detector.

What changed in 2.0.0b1

Version 2.0.0b1 is the point where that model became much more complete.

1. A real code-health model

CodeClone now computes a health score from multiple dimensions:

clones
complexity
coupling
cohesion
dead code
dependencies
coverage

I did not want this to become a decorative “AI score.” The point is not the number by itself; the point is whether the score can be traced back to concrete structural reasons.

That is why the new HTML overview is built around:

a health gauge
KPI cards
an executive summary
source-scope breakdown
a health profile chart

The goal is to answer not only “what failed?” but also “what should I look at first?”

2. Baseline became a first-class contract

In 2.0.0b1, baseline handling is no longer just a convenience file.

It is now a stricter contract with:

trust semantics
compatibility checks
integrity fields
deterministic payload handling
unified clone + metrics baseline flow

That matters a lot in CI. If the baseline itself is not trustworthy, the entire gating story becomes shaky.

3. Dead code arrived, but with explicit suppressions

Dead-code analysis is now part of the model, but I did not want to solve dynamic Python behavior with magic heuristics.

So for intentional runtime-driven cases, CodeClone uses explicit inline suppressions:

# codeclone: ignore[dead-code]
def handle_exception(exc: Exception) -> None:
    ...

or:

class Middleware:  # codeclone: ignore[dead-code]
    ...

That is a deliberate design choice.

I would rather have a local, visible policy mechanism than silently broaden the detector until it becomes hard to reason
about.

4. SARIF was added in 2.0.0b1

This is worth calling out explicitly because I do not want to misrepresent the release: SARIF is new in 2.0.0b1.

I wanted it to be useful beyond “technically yes, there is a SARIF file.”

So the current implementation is designed to work better with IDE/code-scanning workflows, including:

%SRCROOT% anchoring
artifacts
richer rule metadata
location alignment
baseline state for clone results when applicable

5. Detection thresholds got more practical

The default thresholds are now more permissive than before.

That means CodeClone filters out less and analyzes more. For example:

function-level min_loc was lowered from 15 to 10
block thresholds were relaxed
segment thresholds were relaxed

This does increase analysis volume, so it has performance implications. But it also makes the tool more honest. It stops politely ignoring a bunch of small-but-real structural issues.

Why this is useful for AI-generated code

I want to be careful here, because “AI code quality” can turn into hand-wavy marketing really fast.

I am not claiming that CodeClone can detect whether a human or an LLM wrote a piece of code.

That is not the point.

The point is simpler:

AI-assisted development tends to amplify a certain class of structural problems:

repeated patterns with small variations
copy-pasted orchestration logic
overgrown functions
dead callback surfaces
architecture drift that happens in many individually “reasonable” steps

CodeClone is a good fit for that environment because it is:

structural rather than stylistic
deterministic enough for CI
baseline-aware, so it can focus on regression control
explicit about suppressions instead of hiding runtime ambiguity behind heuristics

If your team ships a lot of AI-assisted code, the practical question is not “is AI bad?” It is:

“How do we keep the repository readable, stable, and governable while code is being produced faster?”

That is the problem I think CodeClone helps with.

What it is not

I think first posts do better when they are honest about scope, so here is the short version.

CodeClone is not:

a replacement for SonarQube
a style linter
a security scanner
a magic AI-code detector
a claim that every other tool got the problem wrong

It is a Python-focused, baseline-aware, structural analysis tool with a strong CI orientation.

And yes, it is still beta.

Quick start

If you want to try the prerelease:

pip install --pre codeclone

or:

uv tool install --pre codeclone==2.0.0b1

Then:

codeclone .
codeclone . --html
codeclone . --ci

If you want to adopt the baseline workflow:

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

Where to look next

Docs: https://orenlab.github.io/codeclone/
Live sample report: https://orenlab.github.io/codeclone/examples/report/
PyPI: https://pypi.org/project/codeclone/
GitHub: https://github.com/orenlab/codeclone

Closing thought

If I had to summarize CodeClone 2.0.0b1 in one line, it would be this:

It is the point where the project stopped being “just a clone detector” and became a baseline-aware structural quality
tool for Python CI.

That is the direction I wanted from the beginning.

And with AI-assisted development becoming normal, I think tools in this category are becoming more important, not less.

If this sounds useful, I would be glad to hear what breaks, what feels noisy, what you would want from the CI workflow,
and what kinds of repositories you would actually trust a tool like this on.

DEV Community: orenlab

Structural review that finally knows what your tests cover

1. Bring your coverage.xml into the review

2. Honest about scope: measured vs out-of-scope

3. Typing and docstring coverage are now part of the picture

4. Public API drift becomes a first-class signal

5. Golden fixtures stop showing up as debt

6. Triage that says what it's actually looking at

7. The HTML report got a proper rebuild

8. Claude Desktop launches the right Python

9. Safer and more deterministic under the hood

10. The warm path is actually warm

Wrapping up

Try it

CodeClone b4: from CLI tool to a real review surface for VS Code, Claude Desktop, and Codex

The most interesting new layer: Overloaded Modules

VS Code became a real client, not a demo

Claude Desktop and Codex speak the same contract

Conservative first, deeper only when you mean it

MCP got smarter about guiding agents — and cheaper to talk to

The boring fixes that matter most

What b4 feels like

Try it

I turned my Python code quality tool into a budget-aware MCP server for AI agents

Why MCP mattered for CodeClone

What shipped in 2.0.0b3

What makes this MCP layer different

1. Canonical-report-first

2. Read-only

3. Budget-aware by design

The workflow I wanted agents to follow

Real token cost on a dirty repository

Broad first-pass flow

Guided first-pass flow

Why this matters for PR review

What the MCP surface is good at now

Changed-files review

Safe refactor pick

AI-generated code check

b3 is not only about MCP

The product truth I am taking from this release

Try it (don't forget use --pre)

I built a baseline-aware Python code health tool for CI and AI-assisted coding

I built a baseline-aware Python code health tool for CI and AI-assisted coding

First: I know the ecosystem is not empty

Why I think this matters more now

What CodeClone focuses on

The key idea: baseline-aware governance

What changed in 2.0.0b1

1. A real code-health model

2. Baseline became a first-class contract

3. Dead code arrived, but with explicit suppressions

4. SARIF was added in 2.0.0b1

5. Detection thresholds got more practical

Why this is useful for AI-generated code

What it is not

Quick start

Where to look next

Closing thought

1. Bring your `coverage.xml` into the review

What `b4` feels like

What shipped in `2.0.0b3`

`b3` is not only about MCP

Try it (don't forget use `--pre`)