Documentation

Everything you need to get started with Evolution Engine.

Quickstart

Install

pip install evolution-engine

Analyze a repository

cd your-repo
evo analyze .

EE auto-detects your tools (git history, lockfiles, CI configs) and runs the full 5-phase pipeline: events, signals, explanations, patterns, and advisory.

See what data sources are available

evo sources .

Shows connected adapters and tools detected in your repo that could provide additional signals.

Unlock CI and deployment data (Pro)

evo analyze . --token ghp_your_github_token

Integration Paths

EE supports three integration paths. Start with the CLI, graduate to hooks when you trust the output, and add the GitHub Action for team-wide coverage.

Path 1: CLI             Path 2: Git Hooks          Path 3: GitHub Action
  evo analyze .    -->    evo init --path hooks  -->  evo init --path action
  (manual)                (every commit)              (every PR)

Path 1: CLI (manual)

Already covered above. Run evo analyze . whenever you want to check on your repo.

Path 2: Git Hooks (automatic, local)

Git hooks run analysis on every commit or push automatically. The hook runs in the background and never blocks your commit.

# Set up in one command
evo init . --path hooks

# Or install hooks directly
evo hooks install .

# Use pre-push instead of post-commit
evo hooks install . --trigger pre-push

When the hook detects significant changes, it:

Configuration

Customize hook behavior with evo config set:

# Only notify on critical findings (default: concern)
evo config set hooks.min_severity critical

# Disable desktop notifications
evo config set hooks.notify false

# Disable auto-opening the report
evo config set hooks.auto_open false

# Run hook synchronously (blocks until analysis completes)
evo config set hooks.background false

# Only analyze specific families
evo config set hooks.families "git,ci"

All hook settings:

Management

# Check hook status
evo hooks status .

# Remove hooks
evo hooks uninstall .

Commit Watcher (alternative)

For repos where git hooks aren't practical, use the commit watcher:

# Foreground mode (Ctrl+C to stop)
evo watch .

# Background daemon
evo watch . --daemon
evo watch . --status
evo watch . --stop

Path 3: GitHub Action (CI)

Add Evolution Engine to your pull request workflow. Every PR gets an analysis comment with risk badges.

# Generate workflow file
evo init . --path action

This creates .github/workflows/evolution.yml. The action:

# Sample workflow (generated by evo init)
- uses: evolution-engine/analyze@v1
  with:
    comment: true           # Risk summary on PR
    investigate: true       # AI investigation on High/Critical
    suggest-fixes: true     # Inline fix suggestions
    validate-on-push: true  # Compare on subsequent pushes

All three paths work together. Use hooks for instant local feedback, the Action for team-wide PR coverage, and the CLI for ad-hoc deep dives. Run evo init . --path all to set up everything at once.

CLI Commands

Core

AI Investigation (Pro)

Adapters

Notifications

Patterns & Knowledge Base

History

Adapter Safety

Every adapter is assigned a trust badge automatically:

Adapters can be blocked locally (evo adapter block) or globally via the bundled blocklist. Use evo adapter report to flag broken or malicious adapters.

Setup & Hooks

Configuration

Discovery & Updates

EE includes a lightweight notification system that keeps you informed about available adapters, updates, and community patterns. All checks are privacy-respecting — they only read public PyPI metadata and never send data from your machine.

Adapter Discovery

EE scans your repo for known tools (via config files, lockfiles, and import statements) and checks PyPI for matching adapter packages:

evo adapter discover .
# Available adapters (install via pip):
#   evo-adapter-datadog       v1.0.0   ← Datadog (monitoring)
#   evo-adapter-sentry        v0.2.0   ← Sentry (error_tracking)
#
# Not yet on PyPI (build your own?):
#   evo-adapter-pagerduty     ← PagerDuty (incidents)
#     Scaffold: evo adapter new pagerduty --family incidents

Automatic Notifications

After evo analyze completes, EE checks for adapter updates and new adapters matching detected tools. Notifications appear at the end of the output:

# After evo analyze output:
Notifications:
  Update available: evo-adapter-jenkins 0.1.0 → 0.2.0
  Adapter available: evo-adapter-datadog v1.0.0 (detected Datadog in repo)
  Run `evo notifications dismiss` to clear.

Manage notifications with:

evo notifications list              # View all pending
evo notifications dismiss            # Clear all
evo notifications check .            # Force check now

Community Patterns

Patterns accumulate organically as users analyze repos and share discoveries. EE distributes community patterns through two redundant channels:

If the registry is unavailable, PyPI packages still work. Both channels are checked automatically.

Default Package: evo-patterns-community

The canonical community pattern package is evo-patterns-community, published using CalVer (e.g. 2026.2.15). It contains aggregated patterns from the community registry and is auto-fetched on every evo analyze.

Pattern Packages (auto-fetch from PyPI)

Pattern packages are pip packages on PyPI containing pure data (no executable code). EE downloads the wheel directly, extracts patterns.json, validates it, and imports relevant patterns automatically — no pip install required.

# Auto-fetch happens on every evo analyze
evo analyze .
#   Imported 25 pattern(s) from community registry
#   Imported 25 pattern(s) from community packages

# Add a third-party pattern package
evo patterns add evo-patterns-web-security

# Build your own
evo patterns new my-patterns
evo patterns validate evo-patterns-my-patterns
evo patterns publish evo-patterns-my-patterns

Pattern packages are cached at ~/.evo/pattern_cache.json with a 24-hour TTL. Only patterns matching your locally-detected families are imported.

Registry Push & Pull

Share your anonymized patterns with the community and pull patterns from others:

# Pull community patterns (always allowed)
evo patterns pull .

# Share your patterns (requires opt-in)
evo config set sync.privacy_level 2
evo patterns push .

The registry (codequal.dev/api/patterns) validates all submissions server-side. Patterns require attestations from 2+ independent instances before they are fully trusted.

Pattern Blocklist

Block unwanted pattern packages from being imported:

# Block a package
evo patterns block evo-patterns-untrusted

# Unblock
evo patterns unblock evo-patterns-untrusted

Blocked packages are stored at ~/.evo/pattern_blocklist.json. A bundled blocklist ships with EE for known-bad packages.

Configuration

All update and notification behavior is configurable:

Set DO_NOT_TRACK=1 in your environment to disable all network checks.

How PyPI discovery works: EE queries the public PyPI JSON API (https://pypi.org/pypi/{package}/json) using Python's stdlib urllib.request. No API keys or authentication needed. Results are cached for 24 hours at ~/.evo/version_cache.json.

Build Your Own Adapter

Adapters read from external data sources and feed events into the Evolution Engine pipeline. Each adapter produces events that EE processes through its 5-phase analysis. You can build an adapter for any tool — CI systems, monitoring platforms, issue trackers, deployment tools, etc.

Adapters you build and submit are reviewed by the EE team and, if approved, bundled for all users in future releases.

Step 1: Scaffold

Use the built-in scaffold tool to create a ready-to-publish pip package:

evo adapter new jenkins --family ci

This creates a package directory with:

Step 2: Implement

Your adapter must implement the Adapter Contract. The key method is fetch_events(), which yields event dicts:

class JenkinsAdapter:
    FAMILY = "ci"
    ADAPTER_NAME = "jenkins"

    def __init__(self, repo_path, **kwargs):
        self.repo_path = repo_path
        self.url = kwargs.get("url", "http://localhost:8080")

    def detect(self):
        """Return True if this adapter's data source is available."""
        # Check for Jenkinsfile, .jenkins config, etc.
        return (Path(self.repo_path) / "Jenkinsfile").exists()

    def fetch_events(self, since=None, limit=100):
        """Yield event dicts from the data source."""
        for build in self._get_builds(since, limit):
            yield {
                "event_type": "ci_run",
                "source_type": "jenkins",
                "timestamp": build["timestamp"],
                "payload": {
                    "run_id": build["number"],
                    "status": build["result"],
                    "duration_seconds": build["duration"] / 1000,
                    "trigger": {
                        "commit_sha": build.get("commit", ""),
                    },
                },
            }

Step 3: Test locally

# Install your adapter in development mode
cd evo-adapter-jenkins
pip install -e .

# Verify it passes the contract + security scan
evo adapter validate evo_jenkins.JenkinsAdapter --security

# Or run security scan separately
evo adapter security-check evo_jenkins

# Run EE — your adapter will be auto-detected
evo analyze /path/to/repo-with-jenkinsfile

Step 4: Publish

# Build the package
pip install build
python -m build

# Upload to PyPI
pip install twine
twine upload dist/*

Once published, anyone can install it with pip install evo-adapter-jenkins and EE will auto-detect it via the plugin entry point.

Need help? Use AI

Generate a complete prompt for your AI coding assistant:

evo adapter prompt jenkins --family ci -d "Fetch builds from Jenkins REST API"

This produces a detailed prompt with the full adapter contract, examples, and a validation checklist. Paste it into Claude, ChatGPT, Cursor, or any AI tool.

Adapter Contract

Every adapter must satisfy these requirements to pass evo adapter validate:

Required class attributes

Required methods

Event dict format

{
    "event_type": str,       # e.g. "ci_run", "deploy", "alert"
    "source_type": str,      # matches ADAPTER_NAME
    "timestamp": str,        # ISO 8601 format
    "payload": {
        # Family-specific fields
        "trigger": {
            "commit_sha": str  # Git commit that triggered this event
        }
    }
}

Plugin entry point

In your pyproject.toml, register the entry point so EE can auto-discover your adapter:

[project.entry-points."evolution.adapters"]
jenkins = "evo_jenkins.adapter:JenkinsAdapter"

Submit Your Adapter

Once your adapter passes validation and is published on PyPI:

  1. Test it on at least one real repository
  2. Ensure evo adapter validate passes with no errors
  3. Email us at info@codequal.dev with: your PyPI package name, a brief description, and which family it belongs to
  4. We review the adapter, run our test suite against it, and if approved, bundle it in a future EE release for all users

Accepted adapters get a "Community" badge in the adapter catalog and credit in the release notes.