{"id":"65d64fee-c686-4420-88a0-ee8c66ea13e0","slug":"devready","kind":"mcp","name":"devReady","summary":"A zero-dependency, read-only CLI that checks whether your machine actually meets a project's declared requirements, and tells you exactly what to fix. Built for humans, CI, and AI coding agents (Claud","owner":"Evalogical-Inc","repoUrl":"https://github.com/Evalogical-Inc/devReady","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-16T05:56:54.000Z","addedAt":"2026-10-21T05:20:02.456Z","logoUrl":"https://avatars.githubusercontent.com/u/200181071?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra"],"tags":["ai","ai-agent-tools","ai-agents","cli","cli-app","cli-tool","claude","claude-code"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T00:54:46.798Z","sample":false,"url":"https://conduits.dev/tools/devready","language":"Python","transports":["stdio"],"install":{"pypi":"devready-cli"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<div align=\"center\">\n\n# 🩺 DevReady\n\n### \"Works on my machine\" - finally answered before it wastes your afternoon.\n\n**A zero-dependency, read-only CLI that checks whether your machine actually meets a project's declared requirements, and tells you exactly what to fix.**\nBuilt for humans, CI, and AI coding agents (Claude Code, Codex, any MCP client).\n\n[![CI](https://github.com/Evalogical-Inc/devReady/actions/workflows/ci.yml/badge.svg)](https://github.com/Evalogical-Inc/devReady/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/devready-cli)](https://pypi.org/project/devready-cli/)\n[![npm](https://img.shields.io/npm/v/devready-cli)](https://www.npmjs.com/package/devready-cli)\n[![DevReady](https://img.shields.io/badge/DevReady-%E2%9C%93%20ready-2ea44f)](https://github.com/Evalogical-Inc/devReady)\n[![Website](https://img.shields.io/badge/website-devready--ten.vercel.app-ff6a35)](https://devready-ten.vercel.app/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)\n![Dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen)\n![Status: stable](https://img.shields.io/badge/status-stable-green)\n\n<br/>\n\n<img src=\"https://raw.githubusercontent.com/Evalogical-Inc/devReady/main/docs/devready-demo.gif\" alt=\"Demo of running devready check in a terminal\" width=\"800\"/>\n\n<sub>One command, every requirement checked, exact fixes shown.</sub>\n\n</div>\n\n---\n\n## What is DevReady?\n\nDevReady is a command-line tool that tells you whether your computer is set up to work on a project. Run `devready check` inside a project folder and it:\n\n1. **Reads** the versions the project says it needs (`.nvmrc`, `.python-version`, `package.json` engines, `pyproject.toml` requires-python).\n2. **Compares** them with what is actually installed on your machine (Python, Node.js, npm, Git, and so on).\n3. **Reports** PASS, WARN or FAIL for each item, with what to fix. The exit code is `1` if a requirement is unmet, so it also works in CI.\n\nIt only looks. It never installs, changes or deletes anything, makes no network calls and sends no telemetry. Fixing the problem (for example switching Node versions) is up to you.\n\n## The problem\n\nYou 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.\n\n## The fix\n\n```console\n$ devready check\n\nDevReady - Environment Check\n\n[PASS ] Python       3.15.0 found\n[PASS ] Git          2.52.0 found\n[PASS ] Node.js      23.5.0 found\n[PASS ] npm          11.14.1 found\n[FAIL ] Node engines 23.5.0 does not satisfy package.json engines (>=99)\n[WARN ] Python pin   3.15.0 does not satisfy .python-version (3.99)\n\n4 passed, 1 warning, 1 failed\nNo changes were made to your system.\n```\n\n> 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.\n\n## Why DevReady\n\n| | |\n|---|---|\n| 🎯 **Project-aware** | Reads what *your project* declares (`.nvmrc`, `.node-version`, `.python-version`, `package.json` engines, `pyproject.toml` requires-python) and compares it to what is installed. Not just \"is Node installed?\" |\n| 🔒 **Read-only by design** | Never installs, edits or deletes. Never prints env values. No network. No telemetry. |\n| 🤖 **Agent-ready** | Stable, versioned [JSON schema](docs/schema.json), a Claude Code plugin, an MCP server and `AGENTS.md`. Agents check first instead of guessing. |\n| 🛡️ **Prompt-injection safe** | Output contains only parsed versions and fixed text, never raw file or command output, so a hostile `package.json` can't smuggle instructions to your agent (tested). |\n| 📦 **Zero dependencies** | Pure Python standard library. Installs in a second, runs anywhere Python 3.10+ does. |\n| ⚙️ **CI-friendly** | Documented exit codes, JSON output, tested on Linux, macOS and Windows in CI. |\n\n## Who it's for\n\n- 🧑‍🎓 **Students & bootcamp learners**: plain-language results instead of cryptic stack traces.\n- 🧑‍💻 **Developers switching projects**: one command tells you what's off before you lose an hour.\n- 👩‍🏫 **Maintainers & educators**: put `devready check` in your README's setup steps and cut \"it doesn't work\" issues.\n- 🏗️ **CI & platform teams**: fail fast with a clear preflight step.\n- 🤖 **AI-agent users**: give Claude Code / Codex a ground-truth environment check.\n\n## Install\n\nInstall from [PyPI](https://pypi.org/project/devready-cli/):\n\n```bash\npipx install devready-cli\n# or run without installing:\nuvx devready-cli check\n```\n\nFrom [npm](https://www.npmjs.com/package/devready-cli) (runs the same PyPI release through `uvx` or `pipx`, so one of them must be installed):\n\n```bash\nnpx devready-cli check\n```\n\nNo Python tooling yet (for example a JavaScript-only machine)? `uv` installs without Python, and `uvx` then runs DevReady with no further setup:\n\n```bash\n# macOS/Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# Windows (PowerShell)\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\nuvx devready-cli check\n```\n\nFrom a clone (for development):\n\n```bash\ngit clone https://github.com/Evalogical-Inc/devReady && cd devReady\npython -m venv .venv\n# Windows: .venv\\Scripts\\Activate.ps1    macOS/Linux: source .venv/bin/activate\npython -m pip install -e \".[dev]\"\n```\n\n## Usage\n\n```bash\ndevready check                    # human-readable report for the current directory\ndevready check --quiet            # only non-pass results (text format)\ndevready check --project ../app   # inspect another project's pins\ndevready check --format json      # machine-readable (see docs/schema.json)\ndevready explain docker.daemon    # what a check means and how to fix it\ndevready check --format junit     # or sarif, for CI\ndevready check --only project --skip project.ports   # filter by id or prefix\ndevready fix --plan               # suggested steps only; never runs them\ndevready check --format json > baseline.json   # save a snapshot (commit it for a team baseline)\ndevready check --baseline baseline.json          # show only what changed; fail only on new/worse failures\ndevready init > .devready.json    # optional config: skip ids, require node/python, required env names\ndevready mcp                      # run as an MCP server over stdio\ndevready --version\n```\n\n| Exit code | Meaning |\n|---|---|\n| `0` | No blocking failures |\n| `1` | A project requirement is not met |\n| `2` | Invalid usage (e.g. bad `--project` path) |\n| `3` | Internal error |\n\n| Status | Meaning |\n|---|---|\n| `pass` | Requirement met |\n| `warn` | Tool missing, or a soft pin (`.nvmrc`, `.python-version`) differs |\n| `fail` | A hard requirement (`engines`, `requires-python`) is not met |\n| `skip` | Not evaluated (tool absent, or requirement syntax not understood) |\n| `error` | DevReady couldn't run the check |\n\n### JSON output\n\n```json\n{\n  \"schema_version\": 1,\n  \"results\": [\n    {\n      \"check_id\": \"project.node.engines\",\n      \"title\": \"Node engines\",\n      \"status\": \"fail\",\n      \"summary\": \"23.5.0 does not satisfy package.json engines (>=99)\",\n      \"suggestion\": \"Switch versions with your version manager (nvm, pyenv, mise, ...) or update the requirement.\",\n      \"docs_url\": \"\"\n    }\n  ]\n}\n```\n\n## Use it in CI (GitHub Actions)\n\n```yaml\n- uses: Evalogical-Inc/devReady@v1.3.0\n  with:\n    skip: project.ports                  # optional; also: only, format, project, version\n```\n\nTo show findings in GitHub code scanning, save a SARIF report and upload it. Pin findings point at the file that declares the pin (`package.json`, `.nvmrc`, `go.mod`, ...); tool-only findings have no file.\n\n```yaml\n- uses: Evalogical-Inc/devReady@v1.3.0\n  with:\n    format: sarif\n    output: devready.sarif\n  continue-on-error: true               # still upload when a requirement is unmet\n- uses: github/codeql-action/upload-sarif@v4\n  with:\n    sarif_file: devready.sarif\n```\n\nThe job fails when a declared requirement is unmet (`fail`). It installs `devready-cli` from PyPI, so flags added after your installed release (`--only`, `--skip`, junit/sarif) need a release that includes them; set `version:` to pin one.\n\n## Add the badge\n\nTell contributors your project declares its requirements and can be checked with one command. Paste this into your README:\n\n```markdown\n[![DevReady](https://img.shields.io/badge/DevReady-%E2%9C%93%20ready-2ea44f)](https://github.com/Evalogical-Inc/devReady)\n```\n\n[![DevReady](https://img.shields.io/badge/DevReady-%E2%9C%93%20ready-2ea44f)](https://github.com/Evalogical-Inc/devReady)\n\n## Use it with AI coding agents\n\nDevReady ships the same engine three ways, so your agent can verify the environment *before* it installs, builds or tests.\n\n**Claude Code** - plugin with a skill, a `/devready:doctor` command and an MCP server (the MCP server needs [`uv`](https://docs.astral.sh/uv/); the rest works without it once `devready-cli` is installed):\n\n```text\n/plugin marketplace add Evalogical-Inc/devReady\n/plugin install devready --marketplace Evalogical-Inc/devReady\n```\n\n**Any MCP client** (Codex, Cursor, ...) - one read-only tool, `check_environment`. Also listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.Evalogical-Inc/devready`:\n\n<!-- mcp-name: io.github.Evalogical-Inc/devready -->\n\n```toml\n# ~/.codex/config.toml (verify keys against your Codex version)\n[mcp_servers.devready]\ncommand = \"uvx\"\nargs = [\"--from\", \"devready-cli\", \"devready\", \"mcp\"]\n```\n\n**Anything else** - drop [`AGENTS.md`](AGENTS.md) in your repo, or copy [`skills/devready`](skills/devready/SKILL.md). Details in [docs/agents.md](docs/agents.md).\n\n## Safety & privacy\n\n- Fixed command lists with timeouts; no shell, no user-built commands.\n- Project files are read only if regular files ≤ 1 MB (symlinks skipped) and are never executed.\n- Environment variable values are never read into output. Nothing leaves your machine.\n- A passing report does **not** guarantee your project builds.\n\nSee [docs/security.md](docs/security.md) for the model, [docs/versioning.md](docs/versioning.md) for what stays stable, [docs/checks.md](docs/checks.md) for every check, and [SECURITY.md](SECURITY.md) to report a vulnerability.\n\n## Limitations\n\n- Checks today: Python, Git (+ identity set), Node.js, npm, project pins (`.nvmrc`, `.node-version`, `.python-version`, `.tool-versions`, `package.json` engines, `pyproject.toml` requires-python), `.env.example` vs `.env` key names, Docker CLI + daemon, compose file validity and image platform (arm64 vs amd64) mismatch (only when the project has a Dockerfile/compose file), free disk space, Windows long paths, PowerShell policy, line endings, WSL version and Docker Desktop engine, macOS/Linux build tools, and (only when the project declares them) Go, Ruby, Java, Rust, .NET, pnpm, Yarn and Bun pins, `.env` not git-ignored, `node_modules` vs lockfile, and declared ports already in use.\n- The version-range matcher covers common npm/PEP 440 syntax; pre-releases and exotic ranges report `skip` rather than guess.\n- The Python version compared is the project's (`.venv`/`venv`, else the first `python` on PATH), and the result names the interpreter checked. DevReady does not look at other virtualenv locations (poetry, conda, pyenv shims).\n\n## Roadmap\n\n- [x] Docker CLI + daemon reachability, `.tool-versions`, `.env` key-name diff, disk space, git identity, `devready explain`\n- [x] Port-in-use checks, more ecosystems (Go, Rust, Java, Ruby, .NET, pnpm/yarn/bun), JUnit/SARIF output, `fix --plan`, GitHub Action\n- [x] `.devready.json` config, `--baseline` snapshots\n- [x] Platform-specific checks (Windows, macOS/Linux build tools, WSL)\n- [x] Docker compose validity, image platform, Docker Desktop engine\n- [x] Exact version-switch commands in suggestions (first: `fnm`)\n- [ ] Monorepo `--recursive`, org `--policy` file, VS Code extension (see [ROADMAP.md](ROADMAP.md))\n- [ ] Standalone binaries\n\nHave a setup problem DevReady should catch? [Open an issue](https://github.com/Evalogical-Inc/devReady/issues/new/choose). Early feedback shapes the roadmap.\n\n## Contributing\n\nPRs welcome, especially new read-only checks and platform fixes. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the [technical plan](docs/technical-plan.md); background research is in [docs/research.md](docs/research.md). Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n```bash\nruff check . && ruff format --check . && pytest\n```\n\n## About Evalogical\n\nDevReady is built and maintained by [Evalogical](https://evalogical.com/), a software company offering AI-enabled product engineering, custom software and IT services. Need help with a product or an engineering team? [Talk to us](https://evalogical.com/contactus).\n\n## License\n\n[MIT](LICENSE) © Evalogical Inc\n\n<div align=\"center\">\n\nIf DevReady saved you an afternoon, a ⭐ helps others find it.\n\n</div>\n"}