CodeEvolve

Evaluate how a codebase evolves from git history — taxonomy & phylogeny, Lehman/ecological signals, technical debt, ranked failure points, a provenance ledger for deliberation, a drafted repository report, and an evidence-linked refactor plan.

GitHub URL | local path
    → taxonomy + clade allocation
    → genetics (lineage, gene flow) + ecology (stages, Lehman proxies)
    → metrics + debt + weaknesses
    → provenance ledger (claim → evidence → falsifier)
    → repo report + refactor plan
    → narrative (heuristic | HF Qwen | cloud)

Install

pip install codeevolve

From source:

git clone https://github.com/ehallford11714/codeevolve.git
cd codeevolve
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
# optional local Qwen:
# pip install -e ".[hf]"

For agents (MCP)

Start here: AGENTS.md · details: docs/MCP.md · objective agent: docs/AGENT.md

pip install codeevolve
# or from source:
pip install -e .
# or from GitHub:
pip install "git+https://github.com/ehallford11714/codeevolve.git"
python -m codeevolve.mcp            # stdio MCP server (also: codeevolve-mcp)

Agents should deliberate from frames (claim → evidence → falsifier), not invent history.

# Native coding agent: propose improvements scored by CodeEvolve
python -m codeevolve --repo . agent --objective reduce_debt --max-rounds 2
python -m codeevolve --repo . agent --objective follow_refactor --apply --verify-cmd "pytest -q"

Quick start

# Default: SLM-guided taxonomy (tier=slm)
python -m codeevolve --repo path\to\repo analyze --out report.json --report-out repo_report.md --refactor-out refactor_plan.md

# Swap up for sharper evolutionary studies
python -m codeevolve --model-tier large --repo path\to\repo analyze
python -m codeevolve tiers

# GitHub URL or owner/repo (cloned under ~/.codeevolve/repos)
python -m codeevolve --repo https://github.com/org/repo analyze --max-commits 300

python -m codeevolve --repo org/repo taxonomy
python -m codeevolve --repo org/repo fatigue
python -m codeevolve --repo org/repo risk
python -m codeevolve --repo org/repo report --md-out repo_report.md
python -m codeevolve --repo org/repo refactor --md-out refactor_plan.md
python -m codeevolve hardware

from codeevolve import CodeEvolve

report = CodeEvolve("https://github.com/org/repo").analyze()
print(report.ecology.global_stage, report.debt.score)
print(report.risk.failure_points[0].title)
print(report.refactor_plan.markdown)

LLM backends (optional)

python -m codeevolve --repo . analyze --llm auto
# or: --llm hf-qwen | openai | anthropic | heuristic

$env:CODEEVOLVE_LLM_API_KEY = "..."          # OpenAI-compatible
$env:OPENAI_API_KEY = "..."
$env:ANTHROPIC_API_KEY = "..."
$env:CODEEVOLVE_HF_MODEL = "Qwen/Qwen2.5-0.5B-Instruct"
$env:CODEEVOLVE_SKIP_HF = "1"                # force no local download

hardware / --llm auto picks local Qwen vs cloud vs heuristic from RAM/VRAM/disk (iQueue-style ladder).

What it tracks

Docs

• AGENTS.md — agent connection (install, MCP, tools, rules)
• MCP guide — Cursor/mcp.json, tool loop, CLI fallbacks
• Tutorial — end-to-end workflow incl. provenance & dynamics
• Architecture — pipeline and package map
• Provenance / deliberation — ledger, frames, MCP/schema
• Dynamics — state trajectory rationale (FEAST-aligned)
• Dynamics demo — real-tag walkthrough (examples/demo_dynamics.py)
• Ecology — event/changepoint stage calibration
• Evaluation — synthetic / taxonomy / ecology / dynamics / public / agent
• Agent — objective coding loop (sense → deliberate → act → verify)
• Phylogeny viz — 3D builder (semantic type_path divisions + intent + analysis), clade tree, Fitch parsimony, gene-flow
• Metrics
• Hierarchy · RAG · Semantic
• Cloud / HF Qwen

0.23 — Phylogeny divisions are semantic taxa: keyword type_path (domain/family/kind/specialty) plus niche, with Fitch at each ontology depth. 0.22 — 3D phylogeny builder with commit intent and analysis inspector, plus 2D clade / Fitch parsimony / gene-flow gallery (SVG/HTML/Newick, viz_phylogeny MCP). 0.21 — PR review pack, frame-seeded steps, session delta memory, AST/CST symbol fence, blast-radius preview, coverage-gated tests, agent eval scored on objective delta (included in evaluate --suite all). 0.20 — patch engine, worktree, tool-calling, budgets/HITL. 0.19 — cognitive stack. 0.18 — objective agent + multi-provider LLMs.

python -m codeevolve --repo . provenance --pack --frame frame:basin
python -m codeevolve provenance --schema-out schemas
python -m codeevolve evaluate --suite dynamics
python examples/demo_dynamics.py
python -m codeevolve --repo . analyze --previous report.prev.json --out report.json

# Diff + dashboard + phylogeny viz + PR comment + CI gate
python -m codeevolve --repo owner/repo analyze --out report.json --previous report.prev.json --dashboard-out dash.html --viz-out viz.html
python -m codeevolve viz --report report.json --out viz.html
python -m codeevolve viz --report report.json --out builder.html --kind 3d
python -m codeevolve viz --report report.json --out vizdir/
python -m codeevolve --repo . coupling
python -m codeevolve --repo . clones
python -m codeevolve --repo . dependencies
python -m codeevolve --repo . offboarding
python -m codeevolve --repo . word2vec
python -m codeevolve --repo . semantic-taxonomy
# pip install -e ".[semantic]"  # MiniLM + gensim + chromadb
python -m codeevolve hardware --ensure-embed
python -m codeevolve evaluate --suite synthetic --md-out eval.md
python -m codeevolve evaluate --suite public --md-out public.md   # clones OSS tags
python -m codeevolve comment --report report.json --out pr.md
python -m codeevolve ci --report report.json --previous report.prev.json

License

MIT