The problem

You clone a repo. npm install explodes. The README says "Node 20", your machine has 16, and the error message says nothing useful. Multiply by every new hire, student, CI runner and AI agent that burns tokens guessing why a build failed.

The fix

$ devready check

DevReady - Environment Check

[PASS ] Python       3.15.0 found
[PASS ] Git          2.52.0 found
[PASS ] Node.js      23.5.0 found
[PASS ] npm          11.14.1 found
[FAIL ] Node engines 23.5.0 does not satisfy package.json engines (>=99)
[WARN ] Python pin   3.15.0 does not satisfy .python-version (3.99)

No changes were made to your system.

Output above is from a real run (pins deliberately set to impossible values to show failures). Exit code 1 when a requirement is unmet, so it drops straight into CI.

Why DevReady

Who it's for

• 🧑‍🎓 Students & bootcamp learners: plain-language results instead of cryptic stack traces.
• 🧑‍💻 Developers switching projects: one command tells you what's off before you lose an hour.
• 👩‍🏫 Maintainers & educators: put devready check in your README's setup steps and cut "it doesn't work" issues.
• 🏗️ CI & platform teams: fail fast with a clear preflight step.
• 🤖 AI-agent users: give Claude Code / Codex a ground-truth environment check.

Install

PyPI release is planned. Until then, install straight from GitHub:

pipx install git+https://github.com/Evalogical-Inc/devReady
# or run without installing:
uvx --from git+https://github.com/Evalogical-Inc/devReady devready check

From a clone (for development):

git clone https://github.com/Evalogical-Inc/devReady && cd devReady
python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1    macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev]"

Usage

devready check                    # human-readable report for the current directory
devready check --project ../app   # inspect another project's pins
devready check --format json      # machine-readable (see docs/schema.json)
devready mcp                      # run as an MCP server over stdio
devready --version

JSON output

{
  "schema_version": 1,
  "results": [
    {
      "check_id": "project.node.engines",
      "title": "Node engines",
      "status": "fail",
      "summary": "23.5.0 does not satisfy package.json engines (>=99)",
      "suggestion": "Switch versions with your version manager (nvm, pyenv, mise, ...) or update the requirement.",
      "docs_url": ""
    }
  ]
}

Use it with AI coding agents

DevReady ships the same engine three ways, so your agent can verify the environment before it installs, builds or tests.

Claude Code - plugin with a skill, a /devready:doctor command and an MCP server:

/plugin marketplace add Evalogical-Inc/devReady
/plugin install devready --marketplace Evalogical-Inc/devReady

Any MCP client (Codex, Cursor, ...) - one read-only tool, check_environment:

# ~/.codex/config.toml (verify keys against your Codex version)
[mcp_servers.devready]
command = "uvx"
args = ["--from", "git+https://github.com/Evalogical-Inc/devReady", "devready", "mcp"]

Anything else - drop AGENTS.md in your repo, or copy skills/devready. Details in docs/agents.md.

Safety & privacy

• Fixed command lists with timeouts; no shell, no user-built commands.
• Project files are read only if regular files ≤ 1 MB (symlinks skipped) and are never executed.
• Environment variable values are never read into output. Nothing leaves your machine.
• A passing report does not guarantee your project builds.

See SECURITY.md to report a vulnerability.

Limitations (alpha)

• Checks today: Python, Git, Node.js, npm, and the project pins listed above.
• The version-range matcher covers common npm/PEP 440 syntax; pre-releases and exotic ranges report skip rather than guess.
• The Python version compared is the interpreter running DevReady, not necessarily your project's virtualenv.

Roadmap

• Docker CLI + daemon reachability
• .tool-versions (asdf/mise) and .env.example vs .env key-name diff (names only)
• Port-in-use, disk space, git identity checks
• PyPI release, devready explain <check_id>
• Standalone binaries

Have a setup problem DevReady should catch? Open an issue. Early feedback shapes the roadmap.

Contributing

PRs welcome, especially new read-only checks and platform fixes. Start with CONTRIBUTING.md and the technical plan; background research is in docs/research.md. Please follow the Code of Conduct.

ruff check . && pytest

License

MIT © Evalogical Inc