CodeDelta is a code-churn measurement engine with AI-agent detection — a C++ engine that measures exactly what changed between two versions of a codebase (changed / deleted / added logical statements), plus scanners that find code which runs AI agents and code that may have been written by them.
CodeDelta ships with an MCP server (codedelta_mcp.py, included in every desktop
bundle), so AI agents can call the real engine instead of improvising their own churn
scripts. It speaks the Model Context Protocol over stdio — newline-delimited JSON-RPC
2.0, implemented directly with no SDK dependency; any Python 3.8+ runs it.
Everything executes locally against your working copies: no network calls, nothing leaves your machine.
Three deliberately coarse verbs:
Tool | What it does |
| Measure churn between two directories or two git refs — CHG/DEL/ADD logical statements, REP_CHURN, per-file detail. Same numbers as the GUI and CI, every run. |
| Find code that runs AI agents (named SDK/agent-framework calls) plus agent evidence in git history (co-authorship trailers). |
| Heuristic + ML scan for AI-written code — positioned as pointers for review, not verdicts. |
Related MCP server: codelattice
Download CodeDelta for your platform from codedelta.app/download.html (free and fully unlocked until 31 December 2026 — the licence file is a second one-click download on the same page).
Register the server with your agent. Claude Code example (claude mcp add or
~/.claude.json):
{ "mcpServers": { "codedelta": {
"command": "python3",
"args": ["/path/to/CodeDelta/codedelta_mcp.py"] } } }On macOS (the DMG) the server is at
/Applications/CodeDelta.app/Contents/Resources/codedelta-gui/codedelta_mcp.py.
On Windows it is installed at C:\Program Files\CodeDelta\codedelta_mcp.py; with Python from
python.org use its launcher: "command": "py".
The same engine runs as a GitHub Action on pull requests — live example on a real PR: code-delta-app/demo#2.
Method papers with reproducible figures: codedelta.app/papers.html · User guide: codedelta.app/user-guide.html
Inventory AI agent usage in a codebase: files that import AI SDKs or run agents (with risk ratings and an SDK inventory), plus documentary git-history evidence of agent-signed commits (Co-Authored-By trailers, bot accounts — Claude Code, Copilot, Cursor, Aider and others). Use for questions like 'does this code use AI?' or 'how much of this repo was written by agents?'
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Directory to scan (a git repo enables history evidence) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the detection mechanics (Co-Authored-By trailers, bot accounts, named tools like Claude Code/Copilot/Cursor/Aider) and the shape of results (risk ratings, SDK inventory). It does not state permissions, cost, or scan duration, but the read-only nature is clear from 'Inventory'/'scan'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what is scanned and followed by the question-based use cases; nothing is wasted. The long parenthetical enumerations make the first sentence dense but they earn their place by naming the detected tooling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description must explain returns itself, and it does: import/agent findings with risk ratings, an SDK inventory, and git-history evidence. That is sufficient for correct invocation, though it omits any note on output volume or pagination for large repos.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'dir' parameter is fully documented in the schema, including the note that a git repo unlocks history evidence. The description adds no syntax or format detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Inventory') and resource ('AI agent usage in a codebase') and enumerates the two evidence streams it produces: SDK/agent imports with risk ratings, and git-history evidence of agent-signed commits. It stops short of distinguishing itself from the similarly-named sibling ai_audit, leaving the agent to guess which one to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete triggering questions ('does this code use AI?', 'how much of this repo was written by agents?'), which is clear context for when to reach for it. It offers no exclusions or explicit routing against ai_audit or churn_scan, so the 'when not to use' half is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan source files for characteristics associated with AI-generated code (heuristics + per-language ML models). Returns per-file risk ratings (HIGH/ELEVATED/NORMAL) and an overall AI%. Results are pointers for human review, not verdicts.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Directory to scan | |
| threshold | No | Sensitivity 0-100 (default 50); affects rating cut-offs only |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does a fair amount: it discloses the detection method (heuristics + per-language ML models), the output categories (HIGH/ELEVATED/NORMAL plus an overall AI%), and a calibration caveat that results are not verdicts. It stops short of stating that the operation is strictly read-only, how long a scan takes, or how large directories are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: what it scans, what it returns, and how to treat the results. The core action is front-loaded and every sentence carries distinct information with no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema or annotations, the description covers purpose, output shape, methodology, and interpretation limits, which is enough to call the tool correctly. Gaps remain around read-only behavior and scan cost/scope, but nothing needed to invoke it with the two documented params is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both params (dir, threshold) are already fully documented in the schema, including threshold's 0-100 range, default, and that it only shifts rating cut-offs. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (scan), resource (source files), and detection target (AI-generated code characteristics), plus the methodology (heuristics + per-language ML models). That is far more specific than a tautology, but it never names or contrasts with the siblings churn_scan or agent_scan, so sibling disambiguation is only implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the tool scans code for AI-generation signals and the closing line frames results as human-review pointers, which hints at a triage workflow. There is no explicit when-to-use/when-not guidance and no routing to or away from churn_scan/agent_scan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measure code churn with the CodeDelta engine — deterministic, reproducible numbers (SLOC/LLOC changed, deleted, added, replacement churn) plus HTML reports. Compare two directories, or two git refs of a repository (tags, branches, hashes). Use this instead of improvising diff scripts when the user asks how much code changed.
| Name | Required | Description | Default |
|---|---|---|---|
| new_dir | No | Path to the NEW version (directory mode) | |
| old_dir | No | Path to the OLD version (directory mode) | |
| repo_dir | No | Repository root for git mode (default: current directory) | |
| git_range | No | Git mode: '<oldref>..<newref>' e.g. 'v1.7..v1.8' or 'HEAD~10..HEAD'; bare ref means ref..HEAD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add real behavioral context: deterministic/reproducible results, the metric set, and that HTML reports are produced. However, it never says whether it writes files to disk (and where), whether it is read-only, or what cost/runtime to expect for large repos, so the safety and side-effect profile remains ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, and the core capability plus metric list is front-loaded before the mode explanation and the routing hint. The parenthetical metric enumeration is dense but earns its place by telling the agent what numbers come back.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description compensates by naming the return metrics and the HTML report artifact. What is still missing for a zero-required-parameter tool is clarification of defaults and where reports land; otherwise an agent has enough to invoke it correctly in either mode.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds value the schema does not: it frames the four parameters as two mutually exclusive modes ('two directories, or two git refs'), which is the key semantic an agent needs to pick new_dir/old_dir versus repo_dir/git_range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (measure) plus resource (code churn), and it enumerates the exact metrics produced (SLOC/LLOC changed, deleted, added, replacement churn) and the two comparison modes. The named engine and the explicit 'instead of improvising diff scripts' framing make it unmistakable versus the unrelated siblings ai_audit and agent_scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the triggering user intent ('when the user asks how much code changed') and names an alternative to avoid ('improvising diff scripts'). It also explains that the tool operates in either directory mode or git-ref mode, which guides parameter choice, but it gives no explicit when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0agent_scanai_auditchurn_scanScored across 3 tools
churn_scan is clearly distinct, but ai_audit and agent_scan both target the 'AI in this codebase' question — one measuring AI-generated provenance, the other AI SDK/agent usage and commits. The descriptions help separate them, but a vague query like 'how much AI is in this repo?' could reasonably route to either, creating real misfire risk.
All three follow the same snake_case <subject>_<action> pattern (ai_audit, churn_scan, agent_scan). The verbs vary slightly (audit vs. scan) but the convention is uniform and predictable.
Three tools is well-scoped for a focused code-delta/audit engine, and each covers a genuinely distinct analysis (churn metrics, AI-generated code, AI agent inventory). No filler tools and no redundancy in count.
The three core analyses cover the domain's main questions, and churn_scan produces HTML reports. Minor gaps: no tool to retrieve/correlate prior reports, combine results (e.g. churn vs. AI-generated files), or compare the outputs of the analyses, but these are workable around.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Risk-scan a diff, flag AI-generated-code tells, find secrets. 5 of 7 tools need no account.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Diff two npm/PyPI versions or lockfiles: new install scripts, network/shell/eval calls, new deps.
