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)
pip install codeevolveFrom 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]"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)| Connect | Path |
|---|---|
| Cursor MCP config | .cursor/mcp.json |
| Agent skill | .cursor/skills/codeevolve/SKILL.md |
| Tool loop | analyze_repo → provenance_pack → provenance_expand_frame / provenance_path_pack |
| Improve loop | evolve_toward_objective (or python -m codeevolve agent --objective …) |
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"# 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 hardwarefrom 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)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 downloadhardware / --llm auto picks local Qwen vs cloud vs heuristic from RAM/VRAM/disk (iQueue-style ladder).
| Signal | Meaning |
|---|---|
| Taxonomy / clades | Keyword type hierarchy + co-change clusters; every delta allocated to a clade |
| Build hierarchy | Deep nested “what was built” tree + ecological trend narratives |
| Genetics | File lineage, fitness, gene flow, HGT suspects |
| Ecology | Global + per-clade stages; Lehman law proxies |
| Revert / stability / deps / momentum | Core change-rate metrics |
| Debt | Deprecations, TODOs, historical architecture smells |
| Weaknesses | Ranked failure points (hotspot blast, reverts, bus factor, test gap, …) |
| Repo report | Drafted markdown brief of evolutionary state |
| Refactor plan | Stabilize → contain → pay down → evolve (evidence-linked) |
| Provenance | Ledger + dynamics trajectory (basins, impulses, selection, inter-report diffs) |
- 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
- Context graph — families, coding pivots, decision traces, traversal search, agentic flow
- Metrics
- Hierarchy · RAG · Semantic
- Cloud / HF Qwen
0.25 — Context graph as cognitive control plane: attention_rank seeds coalition/sense, subagents sense-before-reflect, live-graph failure reflections, coalition in reflect + LLM propose. 0.24 — Context graph families (taxon/context/knowledge/decision/pivot/flow), coding pivots with live write-back, policy/why-edges, wavefront traversal search, precedent and delta surfacing. 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.jsonMIT