Evergreen

Evergreen

[Evergreen — Know what breaks next.]

[CI] [Coverage] [npm] [Evergreen] [OpenSSF Scorecard] [OpenSSF Best Practices] [Slipway] [Seaworthy] [CodeQL] [skills.sh]

Evergreen finds end-of-life and deprecated runtimes, packages, and GitHub Actions in your repository, shows the exact file and line, and backs every finding with an authoritative source, a replacement, and migration steps. It runs on your machine as a CLI, a local MCP server, a GitHub Action (with SARIF for code scanning), and an Agent Skill, so people and coding agents can find lifecycle risk before it breaks a build, and check a dependency before adding it. Scans are deterministic and offline, and need no account.

Read this in: English · فارسی.

Read the public documentation, run the 90-second demo, or inspect the validation report. For AI tools, the docs are also published as llms.txt and llms-full.txt.

For coding agents

npx evergreen-deprecation check pkg:npm/[email protected]   # before adding a dependency: prints a status (affected or no-data) with its sourcenpx evergreen-deprecation scan                           # in a repository: prints each lifecycle risk with its file, line, and sourcenpx --yes --package evergreen-deprecation evergreen-mcp  # start the local MCP server over stdio for an agent host

What it covers

The level in parentheses is the detector's maturity; the full list with each level is the ecosystem coverage matrix, and earned precision and recall per detector are on the accuracy dashboard. Each finding carries its rule's sources, review date, and migration steps; see Lifecycle rules. Other ecosystems are not guessed at: Evergreen reports a package it has no rule for as no-data, never as safe, and new ecosystems start from a generated detector skeleton. The compatibility matrix lists supported environments and hosts.

Why not just Renovate?

Renovate, Dependabot, and endoflife.date each answer a question Evergreen does not, and Evergreen answers one none of them does: what is ending in this repository, and where is it used. Most repositories gain from running one of them with Evergreen, so the table states what each covers and what it does better, and links the source of every claim. Details and sources per tool are in Evergreen compared with other tools.

Product principles

• Local-first: source code stays on the user's machine or CI runner.
• Deterministic core: findings do not require an LLM.
• Evidence-backed: every deprecation claim links to an authoritative source.
• Agent-ready: every human-readable report has a machine-readable equivalent.
• Extensible: ecosystems are added through detectors rather than core rewrites.

Quickstart

The five-step quickstart has copy-paste commands and expected output for each step.

Requirements: Node.js 22 or newer.

npx evergreen-deprecation scan .

For coding agents, install the Agent Skill with one command. It teaches your agent to find, explain, and migrate these findings, and it is listed on skills.sh:

npx skills add arminazimi/evergreen

Give an agent a short answer instead of the full report: one line per finding with its id, location, severity, and replacement, most severe first, capped at 25 findings (the rest are counted) and under 8 KiB:

npx evergreen-deprecation scan . --format compact

Verify that the CLI, local MCP server, Agent Skill, plugin foundations, and CI workspace are ready without changing configuration or uploading repository data:

npx evergreen-deprecation doctor .npx evergreen-deprecation doctor . --json

See the public compatibility matrix for supported, experimental, and unsupported combinations.

Discover Evergreen's versioned capabilities and entry points programmatically:

npx evergreen-deprecation capabilities --json

The auto-discovery contract defines the shared identifiers used by the CLI, MCP server, Agent Skill, plugins, and CI integrations.

Create a baseline for accepted existing findings, then report only new lifecycle regressions:

npx evergreen-deprecation baseline .npx evergreen-deprecation scan . --baseline .evergreen-baseline.json

Check a single dependency before adding it, without scanning a repository:

npx evergreen-deprecation check pkg:npm/[email protected]npx evergreen-deprecation check pkg:github/actions/checkout@v4 --json

The command prints the lifecycle problem, replacement, and evidence, and exits 1 when a rule at or above --fail-on (default high) applies, 0 otherwise, 2 for a wrong command line, and 4 for a Package URL that cannot be parsed (see exit codes). A package Evergreen has no rule for reports no-data, which is not a claim that it is safe. Without a version, a package whose rules only cover some versions reports version-dependent; add a version to get a definite answer.

Lifecycle rules can be refreshed between releases from signed bundles, and scans stay offline unless you ask:

npx evergreen-deprecation data statusnpx evergreen-deprecation data update

See Lifecycle data for the signing and trust model, pinning, and what happens when a download cannot be verified.

Inspect the evidence and migration direction for one result:

npx evergreen-deprecation explain '<finding-id>' .

Generate portable migration context for a human or coding agent:

npx evergreen-deprecation context '<finding-id>' . --json

Migration packets contain rule-specific constraints and steps, exact affected files and usages, authoritative sources, and suggested verification commands. Evergreen never executes those commands automatically. See the migration packet guide.

Tell the coding agents working in a repository to check dependencies before adding them. This adds (or refreshes) a clearly marked section in AGENTS.md, or CLAUDE.md if that is the file you have; running it again changes nothing, and nothing outside the markers is touched:

npx evergreen-deprecation init --agents --dry-run   # show the changenpx evergreen-deprecation init --agents

To do this for every coding agent a repository is already set up for, run setup. It detects Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and Kilo Code configuration, shows the change for each host's instruction file, and writes only after you confirm (or pass --yes). It uses the same marked section as init --agents, so existing rules are never overwritten:

npx evergreen-deprecation setup --dry-run   # print the plannpx evergreen-deprecation setup             # ask, then writenpx evergreen-deprecation setup --yes       # no prompt (CI, scripts)

Connect a coding agent through the local MCP server:

npx --yes --package evergreen-deprecation evergreen-mcp

The stdio server exposes scan_repository, list_deprecations, explain_deprecation, create_migration_context, verify_migration, and check_dependency (check one package before adding it). See the local MCP guide for host configuration, the intended workflow, and privacy guarantees.

Agent Skill

Install the vendor-neutral Agent Skill from the monorepo:

npx skills add arminazimi/evergreen

Pull future revisions with:

npx skills update evergreen-deprecation

The evergreen-deprecation Skill teaches discovery, explanation, migration, and verification while leaving detection and migration logic inside Evergreen. It is discoverable on skills.sh and has been install-validated for Codex, Claude Code, Cursor, GitHub Copilot, and Gemini CLI. See the Agent Skill guide for evaluation, compatibility, limits, and security assumptions.

Codex and Claude plugin packages are generated from that same Skill and MCP workflow. Their packaging architecture keeps host manifests thin and fails CI when either package drifts from the canonical sources. The cross-host evaluation publishes shared-corpus results, context budgets, permission behavior, and security limitations; the same checks block release regressions in npm run check.

Evergreen runs locally and does not upload repository contents. Which commands read the filesystem, read the environment, spawn processes, or use the network is spelled out in the command and surface access table (also summarized in SECURITY.md).

Development

npm installnpm run check

The initial detector reports unsupported major versions of five first-party actions with exact file and line locations:

• actions/checkout
• actions/setup-node
• actions/cache
• actions/upload-artifact
• actions/download-artifact

Pinned commit SHAs and dynamic expressions are intentionally left unclassified until Evergreen can resolve them without guessing.

The npm detector also reads package.json, npm/pnpm/Yarn lockfiles, Node.js runtime declarations, and a small evidence-backed registry of deprecated direct dependencies. Use evergreen explain <finding-id> to inspect a finding and its sources. If a finding is wrong, evergreen report-issue <finding-id> prints a Markdown report with the rule, its evidence, and a few redacted lines of the declaring file, and never opens an issue or uses the network.

The Python detector reads PEP 621 and Poetry metadata from pyproject.toml, requirements*.txt, common runtime-version files, and uv/Poetry/PDM/Pipenv lockfiles. It reports unsupported Python declarations and lifecycle risks in direct dependencies while ignoring transitive-only lockfile entries.

Source usage analysis

Package lifecycle findings now include the concrete imports, calls, and configuration keys that make a migration necessary. Matching is language-aware and alias-aware for JavaScript, TypeScript, and Python, with configuration-key support for JSON, YAML, TOML, INI, and Python settings. Each match includes its exact file, line, column, and source excerpt, plus a migration-impact estimate based on affected usages and files.

The analyzer scans the repository once for a batch of detector contracts and ignores generated, dependency, build, and environment directories. Run the repeatable accuracy and scan-time benchmark with:

npm run benchmark:usage

See the benchmark notes for the corpus and interpretation.

GitHub Action

Evergreen can annotate pull requests, suppress accepted findings with a baseline, fail on a chosen severity, and upload the complete JSON report:

permissions:  contents: read
steps:  - uses: actions/checkout@v7  - uses: arminazimi/[email protected]    with:      baseline: .evergreen-baseline.json      fail-on-severity: high

Pin a full commit SHA instead of a version tag when your threat model requires immutable third-party action references. See the GitHub Action guide for setup, inputs, permissions, artifacts, and privacy boundaries.

Detector SDK

External detectors can use the versioned interface exported by evergreen-deprecation/sdk. The scan engine composes compatible detectors without importing any built-in implementation.

See the detector authoring guide and the minimal detector example.

Initial product shape

The CLI is the product. Detectors extend it, GitHub Actions automate it, and the local MCP server exposes it to agents. A hosted backend is intentionally outside the roadmap; lifecycle data updates through a signed, offline-verifiable data channel instead.

See the roadmap, architecture, brand guide, contribution guide, and security policy.

Community

Questions, ideas, and things you built with Evergreen belong in GitHub Discussions: use Q&A to ask, Ideas to propose, and Show and tell to share. Use issues for bugs, lifecycle rule requests, and ecosystem requests. How decisions are made, who reviews what, and what happens when a detector loses its owner is in GOVERNANCE.md. Who owns each detector is in MAINTAINERS.md.

License and brand

Evergreen source code is licensed under the Apache License 2.0. The lifecycle dataset in packages/data (published as evergreen-data) is licensed under CC BY 4.0; its attribution notice is in packages/data/ATTRIBUTION.md. The Evergreen name, logo, and files in brand/ are proprietary brand assets and are covered by separate brand asset terms.