agent-versions

Dependabot for AI coding. AI agents write dependency versions from training data that is months old. agent-versions gives them, and you, the real latest versions live from npm, PyPI, crates.io and the Go module proxy. It also keeps a continuously refreshed snapshot of every package that Claude Code, Codex, Gemini CLI and other AI coding tools depend on.

It ships in several forms, so it fits wherever you work:

Supports package.json (including overrides and pnpm/bun catalogs), pyproject.toml (PEP 621, dependency groups, uv, Poetry), requirements*.txt, Cargo.toml (including workspaces) and go.mod. Zero dependencies. Node 20+.

Quick start

# What's outdated in this project? (recursive, monorepo-friendly)
npx -y github:AndrewTtofi/versions check

# Upgrade everything, holding back breaking (major) upgrades
npx -y github:AndrewTtofi/versions update --no-major
npm install   # or pnpm/uv/cargo/go - lockfiles are yours to refresh

# Latest version of anything
npx -y github:AndrewTtofi/versions latest next pypi:fastapi cargo:tokio go:github.com/spf13/cobra

# Latest Claude Code / Codex / Gemini CLI / ... and how to install them
npx -y github:AndrewTtofi/versions tools

# Set a project up so it stays current (see below)
npx -y github:AndrewTtofi/versions init --no-major --mcp

update changes only the version text. It keeps your range style (^, ~, >=, ==, ~=), your precision (tokio = "1" stays at one component until 2.0 exists), and all formatting and comments. It never downgrades. It skips workspace:, file:, git, path and complex ranges, and tells you why.

Related MCP server: package-version-check-mcp

Keep every project current

Run init once in a project:

npx -y github:AndrewTtofi/versions init --no-major --mcp

It works out which coding companions the project uses and writes:

• .github/workflows/agent-versions.yml: runs daily, opens (or refreshes) one PR with a table of what changed, and auto-merges it when it's safe (see below).

• AGENTS.md plus each companion's own rules file: a short rule telling the agent to look versions up instead of guessing, and how to upgrade (table below).

• MCP configs (with --mcp): connects the MCP server for everyone who opens the project, in every companion that supports project-level MCP. Existing files are merged, and files with comments are never overwritten; you get the snippet to paste instead.

• agent-versions.json: project config (see Configuration).

Companions are detected from their config files. Use --for cursor,windsurf to choose, --for all for every companion, or --for list to see them.

Automatic merging

The generated workflow has three jobs, each with only the permissions it needs:

update     new releases older than --min-age days -> rewrite manifests -> refresh lockfiles
           (install scripts disabled) -> open/refresh one PR               [contents+PR write]
verify     check out the PR, run VERIFY (install + tests)                  [read-only, no secrets]
automerge  if verify passed and the largest change <= AUTOMERGE -> squash-merge
           otherwise label it needs-review and comment                     [contents+PR write]

npx -y github:AndrewTtofi/versions init --automerge minor --min-age 3 --verify "npm ci && npm test"

These are the AUTOMERGE/VERIFY env values and args in the workflow file, so you can edit them there later.

Enable Settings → Actions → General → Allow GitHub Actions to create and approve pull requests and Settings → General → Allow auto-merge. With branch protection and required checks, the PR uses GitHub's native auto-merge and waits for them. Add a secret AGENT_VERSIONS_TOKEN (a fine-grained PAT or GitHub App token with contents and pull-requests write) if your own CI should run on the PR, or if the merge should trigger deploy workflows. Events created by the default GITHUB_TOKEN don't trigger other workflows.

Majors are never merged under the default policy. You get a labelled PR to review instead.

Claude Code plugin

/plugin marketplace add AndrewTtofi/versions
/plugin install agent-versions@agent-versions

The plugin bundles:

• the MCP server (runs locally with node; nothing to install),

• a latest-versions skill that fires whenever the agent adds, pins or upgrades a dependency or writes install commands, and

• a SessionStart hook that puts a short list of outdated dependencies into the agent's context each time you open a project. Set AGENT_VERSIONS_HOOK=off to turn it off.

MCP server (Codex, Gemini CLI, Cursor, Claude Code, ...)

The server runs over stdio: npx -y github:AndrewTtofi/versions mcp.

Claude Code (without the plugin)

claude mcp add agent-versions -- npx -y github:AndrewTtofi/versions mcp

OpenAI Codex: ~/.codex/config.toml

[mcp_servers.agent-versions]
command = "npx"
args = ["-y", "github:AndrewTtofi/versions", "mcp"]

Gemini CLI: ~/.gemini/settings.json. Cursor: .cursor/mcp.json. VS Code: .vscode/mcp.json (use "servers" there).

{
  "mcpServers": {
    "agent-versions": { "command": "npx", "args": ["-y", "github:AndrewTtofi/versions", "mcp"] }
  }
}

Tools

Remote connector (claude.ai, team-wide)

The same server speaks MCP Streamable HTTP. Remote mode leaves out the two filesystem tools; the agent uses check_manifest instead.

npx -y github:AndrewTtofi/versions mcp --http --port 3000                 # 127.0.0.1 only
npx -y github:AndrewTtofi/versions mcp --http --host 0.0.0.0 --port 3000  # behind your reverse proxy

The connector enforces a per-client rate limit (AGENT_VERSIONS_RATE_LIMIT, default 120/min), body and batch size caps, and an Origin allow-list (AGENT_VERSIONS_ALLOWED_ORIGINS). Browsers are rejected unless their origin is listed. See SECURITY.md.

Or deploy the repository as-is to a serverless host. api/mcp.js is a ready-made function entry point (on Vercel: vercel deploy, endpoint https://<app>/api/mcp). Then in claude.ai go to Settings → Connectors → Add custom connector and paste the URL. The endpoint is read-only and stateless, and it needs no secrets.

GitHub Action

- uses: actions/checkout@v7
- uses: AndrewTtofi/versions@v0.3.0   # pin a release or commit SHA
  id: versions
  with:
    args: --no-major --exclude "eslint*"   # any CLI flags
    # mode: check                           # report only; fails the job when outdated
- uses: peter-evans/create-pull-request@v8
  with:
    title: 'chore(deps): update dependencies to latest releases'
    body: ${{ steps.versions.outputs.report }}

Outputs: report (a Markdown table) and outdated (a count).

CLI reference

agent-versions <command> [options]

  check [dir]       Report dependencies with newer releases (default command)
  update [dir]      Rewrite manifests to the latest releases
  latest <pkg...>   Latest version of packages
  tools             Latest versions of AI coding tools
  stack <tool>      Dependencies an AI tool uses, with latest versions
  init [dir]        Config + scheduled update PRs + agent instructions (--mcp, --no-workflow, --no-agents)
  mcp               MCP server over stdio (--http [--port N] for remote)

  --no-major        Hold back breaking upgrades (1.x→2.x, 0.3→0.4)
  --tracked [--tool <id>]  Only touch deps that tracked AI tools also use (optionally one tool)
  --snapshot        Use the published snapshot instead of live registries (fast, reproducible)
  --min-age <days>  Hold releases younger than this   --exclude a,b*    Leave packages alone          --peer / --indirect   Include peer deps / indirect Go deps
  --dry-run         Preview update                --fail               check exits 1 when outdated (CI)
  --brief | --json  Output formats                --no-recursive        Top-level manifests only

Configuration

agent-versions.json in the project root. CLI flags override it.

{
  "noMajor": true,
  "exclude": ["react", "react-dom", "@types/*"],
  "include": [],
  "includePeer": false,
  "includeIndirect": false,
  "tracked": false,
  "minReleaseAgeDays": 3,
  "source": "live"
}

Environment: AGENT_VERSIONS_NPM_REGISTRY, AGENT_VERSIONS_PYPI, AGENT_VERSIONS_CRATES_INDEX, GOPROXY (mirrors and private registries), AGENT_VERSIONS_SNAPSHOT_URL (your own fork's feed), and AGENT_VERSIONS_HOOK=off.

How the feed stays fresh

.github/workflows/update-snapshot runs once a day (05:17 UTC), and on demand via "Run workflow". For every tool in sources.json it:

1. resolves the tool's own latest versions (npm, PyPI, GitHub releases),

2. finds every manifest in its public repositories, skipping tests, examples, docs and vendored code, or reads the published package's dependencies for closed-source tools,

3. drops the repository's own internal packages, then resolves the latest release of every remaining dependency,

4. publishes latest.json and VERSIONS.md to the data branch if anything changed. main is protected and is never written by automation.

The CLI and MCP tools query registries live by default, so they are never more out of date than the registries themselves. The snapshot powers tools, stack, --tracked and --snapshot, and serves as an offline fallback.

Tracked today (29): Claude Code & Claude Agent SDK, OpenAI Codex, Gemini CLI, GitHub Copilot CLI, GitHub Copilot Chat, Cursor, opencode, Qwen Code, Crush, goose, Aider, Cline, Continue, OpenHands, Kilo Code, Amp, Augment (Auggie), Factory Droid, JetBrains Junie, CodeBuddy, Letta Code, Mistral Vibe, Grok CLI, Zed, gptme, SWE-agent, and the MCP, OpenAI Agents and Agent Client Protocol SDKs. Closed-source tools are tracked through their published packages or update feeds. To add a tool, see CONTRIBUTING.md.

Programmatic use

import { analyze, applyUpdates, createResolver } from 'agent-versions';

const analysis = await analyze('.', { noMajor: true });
await applyUpdates(analysis);

Security

agent-versions is a supply-chain component, so it's built defensively:

• It never writes a version that fails strict validation.

• It never builds a registry URL from an unvalidated name.

• Local MCP tools can't leave the project directory.

• The public connector is read-only and rate-limited.

• The repository runs SHA-pinned, least-privilege workflows behind a protected main.

Details and reporting are in SECURITY.md.

Contributing

PRs are welcome. See CONTRIBUTING.md. If you're working with an AI agent, it should read CLAUDE.md. Please follow the Code of Conduct.

License

MIT