Cross-platform diagnostics, reproducibility auditing and safe repair planning for developer machines, project toolchains, SDKs, containers and build dependencies.
Created, founded and led by @webdevsamran.
"Works on my machine" is not one bug — it's a class of bugs:
- Which developer tools/versions are installed — and which one actually runs?
- Are multiple conflicting versions of Python/Node/Java present?
- What does this project actually require, and what's missing or incompatible?
- Why does machine A build the project while machine B fails?
- Is Docker/WSL/container tooling healthy?
- Are PATH, SDK, compiler, proxy or certificate settings wrong?
- Is the GPU/AI development stack compatible with the project?
Most tools answer one of these. DevRepro Doctor answers all of them in a single read-only scan — then tells you what can be fixed safely.
It is not another machine cleaner and not another environment installer. It is:
project-aware developer-environment diagnostics
- reproducibility snapshots
- machine-to-machine diffs
- explainable safe remediation
pip install devrepro-doctor
devrepro doctor # full read-only diagnostic scanWhat a scan looks like. The block below is generated by
scripts/capture_readme_example.py, which renders a
fixture through the same render_terminal_table the command calls, and CI fails if the two
drift apart. The findings are illustrative -- a real scan reports your machine -- but the
layout and the rule ids are the program's, not prose:
$ devrepro doctor
DevRepro Doctor v0.2.0 — Windows
┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ State ┃ Rule ┃ Summary ┃
┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ BLOCKED │ containers/docker-daemon-unreachable │ Docker CLI 29.7.2 present but daemon │
│ │ │ unreachable. Connection refused. │
│ ERROR │ node/version-mismatch │ node 18.19.0 does not satisfy required range │
│ │ │ >=20.0.0. │
│ WARN │ path/duplicates │ 7 duplicate PATH entries detected. │
│ WARN │ python/multiple-versions │ Multiple Python versions installed: 3.10.11, │
│ │ │ 3.11.9, 3.12.4. Active: 3.12.4 │
│ │ │ (official-installer). │
└─────────┴──────────────────────────────────────┴─────────────────────────────────────────────────┘
Read-only scan. No data left this machine.devrepro snapshot -o my-machine.json # privacy-sanitized manifest
# ... send to teammate / CI / support engineer ...
devrepro diff mine.json theirs.json # why does it work there?Diff classification: same, version-drift, missing, extra,
path-precedence, platform-expected, project-critical.
Output to terminal, JSON or standalone HTML.
Probes only observe; rules only judge; nothing writes to your machine unless
you confirm a remediation. The privacy gate sits between the in-memory report
and every output, so redaction cannot be bypassed by reaching for a different
format. Boxes are real packages under devrepro/:
flowchart LR
subgraph observe [Read-only observation]
PROBES[probes/<br/>tools · PATH · network · GPU]
PLATFORMS[platforms/<br/>OS-specific detection]
PROJECT[project/<br/>declared requirements]
end
PROBES --> CTX[core/<br/>ScanReport model]
PLATFORMS --> CTX
PROJECT --> CTX
POLICY[.devrepro.toml<br/>policy] --> RULES
CTX --> RULES[rules/<br/>packs: python · node · go · containers ...]
RULES --> FIND[Findings<br/>PASS · INFO · WARN · ERROR · BLOCKED]
FIND --> REMED[remediation/<br/>planner: SAFE · LOW · MEDIUM · HIGH]
REMED -.never automatic above LOW.-> USER([you confirm])
FIND --> GATE[privacy/gate<br/>redact + secret-scan]
GATE --> REPORTS[reports/<br/>terminal · JSON · Markdown · JUnit · HTML]
GATE --> SNAP[snapshots/<br/>signed manifest]
SNAP --> DIFF[diff/<br/>machine-to-machine comparison]
REPORTS --> SERVER[server/ + web/<br/>local UI]
- Read-only by default. Nothing on your system is modified without an explicit, confirmed remediation step.
- No telemetry. No cloud upload. Ever.
devrepro servebinds to localhost only. - Redaction before serialization. Usernames, home directories, tokens, API keys, SSH/cloud/registry credentials and private hosts are redacted; probable secrets block snapshot/report export entirely.
- Every report states exactly what was collected and its redaction status. See docs/PRIVACY.md for the complete inventory.
| Windows | Linux | macOS | |
|---|---|---|---|
| Core diagnostics | ✅ | ✅ | ✅ |
| WSL doctor | ✅ | n/a | n/a |
Detected toolchains include: Git/GitHub CLI, Python (+pyenv/conda/uv), Node (+nvm/fnm/volta), Java, .NET, Go, Rust, PHP, Ruby, C/C++ (MSVC/gcc/ clang), CMake/Ninja, Docker/Podman, kubectl, Terraform, cloud CLIs (AWS/ Azure/gcloud), WSL, Homebrew, apt/dnf/pacman, Chocolatey/winget/Scoop, GPU/AI stacks (CUDA, ROCm, oneAPI, DirectML, Metal).
Commit a .devrepro.toml so every contributor's machine is checked against
the same contract:
[supported_os]
windows = true
linux = true
macos = true
[required_runtimes]
python = ">=3.11,<3.14"
node = ">=20"
[required_tools]
git = "*"
docker = ">=24"
[known_bad_versions]
node = ["<=16"] # EOL line
[containers]
require_devcontainer = true
[required_env_names] # NAMES only — never values
names = ["DATABASE_URL", "API_TOKEN"]devrepro check --policy .devrepro.tomlA production-quality React + TypeScript frontend ships under web/
(Home, Machine Overview, Project Readiness, Toolchains, PATH Explorer,
Findings, Environment Diff, Snapshots, Rules, Remediation Plan, History,
Docs, Contributors, About). It reads sanitized JSON exports or the optional
localhost API served by devrepro serve.
Run it locally with npm ci && npm run dev in web/, or point it at a
running devrepro serve.
Diagnostics doctor check info scan preflight guard path which platform-depth
Project project monorepo ci-diff profile baseline generate
Environment env ports git-health network envmanagers
Snapshots snapshot diff history drift sign-snapshot verify-snapshot bundle
Remediation plan fix rules plugins
Reports report export
Services serve self-test server-backup server-restore
All major commands support --json and stable exit codes (0 ready,
1 warnings, 2 blocked, 3 internal error) for use in onboarding
scripts and CI.
Gate your workflow on machine readiness and surface findings directly on GitHub pull requests via SARIF:
- uses: webdevsamran/devrepro-doctor/action@main
with:
command: preflight
sarif-output: devrepro.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: devrepro.sarifSee docs/ci-github-actions.md for the full guide.
- ARCHITECTURE.md — module map and data flow
- ROADMAP.md — where we're going
- CONTRIBUTING.md — how to help
- SECURITY.md — reporting vulnerabilities
- docs/PLUGINS.md — plugin API reference
Issues labeled good first issue cover project detectors, platform probes,
toolchain detection, WSL, containers, GPU stacks, rule packs, safe
remediations and frontend visualizations. See CONTRIBUTING.md to get started.
Also by @webdevsamran:
-
api-verity-lab — API contract governance. Spec diffing with stable change ids, direction-aware breaking-change rules, schema-driven testing, runtime drift detection, traffic replay and performance budgets for OpenAPI, AsyncAPI, GraphQL and gRPC.
-
tooltrace-bench — vendor-neutral, reproducible benchmarking of AI agents on real tool-use tasks: coding, file operations, multi-step workflows and failure recovery, scored deterministically from traces rather than from the agent's own account of what it did.
-
local-ai-hardware-bench — vendor-neutral benchmarking of local AI runtimes across CPUs, GPUs, NPUs and edge accelerators. One loadgen drives every backend, and every published number carries the hardware, driver, runtime version, model checksum and seed that produced it.
These are independent projects: no shared library, no coupled releases, and each is usable on its own. What they do share is a rule — anything a README or a report claims has to be traceable to something the code actually produced, which is why each of them checks its own documentation in CI.
Apache License 2.0 — see LICENSE. Creator attribution: @webdevsamran.