🔩 devdoctor

Run diagnostics on your development environment — detect tools, check versions, verify configs, prescribe fixes.

Features • Install • Usage • Profiles • License

  🔩 devdoctor — Development Environment Diagnostics
  ────────────────────────────────────────────────
  📅 2026-04-01 00:02 · mymachine

  🖥️ System
  ────────────────────────────────────────
  ✔  System Info      │ Darwin 25.5.0 (arm64) · Python 3.14.3
  ✔  Shell            │ zsh (/bin/zsh)
  ✔  Homebrew         │ Homebrew 5.1.1
  ✔  Disk Space       │ 12Gi/228Gi used (36%) — 21Gi available

  👾 Languages & Runtimes
  ────────────────────────────────────────
  ✔  Python           │ Python 3.14.3
  ✔  Node.js          │ v23.11.0
  ✔  Go               │ go1.25.6 darwin/arm64
  ✔  Rust             │ rustc 1.92.0

  📂 Version Control
  ────────────────────────────────────────
  ✔  Git              │ git version 2.49.0
  ✔  Git Config       │ user: you <you@email.com>
  ⚠  SSH Keys         │ No SSH key found

  ════════════════════════════════════════════════

  📊 Health Score:  88/100  Grade A
    [██████████████████████████░░░░]

  ✔ Passed: 39   ⚠ Warnings: 3   ✘ Failed: 0   Total: 44

✨ Features

• 🩺 Comprehensive Health Check — Scans 40+ items across 10 categories: system, languages, VCS, build tools, DevOps, editors, dev tools, network, security, Python environment
• 🎨 Beautiful Terminal Report — Color-coded output with ✔/⚠/✘ icons, health score, and grade (A–D)
• 📊 Health Score — Quantified 0–100 score with visual progress bar
• 🔧 Fix Suggestions — --fix flag shows actionable fixes for every issue found
• 📋 Multiple Profiles — all, web, devops, python profiles for focused checks
• 📄 JSON Output — Machine-readable --json flag for CI/CD pipelines
• 🔇 Quiet Mode — --quiet to only show warnings and failures
• 🐍 Zero Dependencies — Pure Python 3.8+, no pip install needed
• 🖥️ Cross-Platform — Works on macOS, Linux, and WSL

📦 Installation

Direct download (recommended):

# Clone and run
git clone https://github.com/nadonghuang/devdoctor.git
python3 devdoctor/devdoctor.py

One-liner (no clone needed):

python3 -c "$(curl -fsSL https://raw.githubusercontent.com/nadonghuang/devdoctor/master/devdoctor.py)"

Install as a command:

pip install git+https://github.com/nadonghuang/devdoctor.git
devdoctor

🚀 Usage

# Run full diagnostics
python3 devdoctor.py

# Check only web developer essentials
python3 devdoctor.py --profile web

# Show fix suggestions for issues
python3 devdoctor.py --fix

# JSON output for scripts and CI/CD
python3 devdoctor.py --json

# Only show warnings and failures
python3 devdoctor.py --quiet

# Combine flags
python3 devdoctor.py --profile python --fix

Programmatic Usage

from devdoctor import (
    check_system, check_languages, check_vcs,
    check_security, check_dev_tools, render_json
)

# Run specific checks
results = check_system() + check_languages() + check_vcs()

# Get JSON output
print(render_json(results))

🎯 Profiles

Profile	Description	Checks
all	Full checkup (default)	System, Languages, VCS, Packages, Dev Tools, Security, Disk, Network, Dotfiles, Python
web	Web developer essentials	System, Languages, VCS, Packages, Dev Tools, Disk, Network
devops	DevOps engineer essentials	System, Languages, VCS, Dev Tools, Security, Disk, Network
python	Python developer essentials	System, Languages, VCS, Packages, Python env, Disk, Network

🔍 What It Checks

🖥️ System

• OS and architecture
• Default shell (zsh/bash/fish)
• Terminal emulator
• Homebrew installation
• Disk space usage
• Dotfiles presence

👾 Languages & Runtimes

• Python, Node.js, Ruby, Go, Rust, Java, PHP
• Version compatibility checks (e.g., Node.js ≥ 18 LTS)

📂 Version Control

• Git installation and version
• Git user.name / user.email configuration
• SSH keys for GitHub/GitLab
• GPG signing key setup

🔒 Security

• Firewall status (macOS)
• Suspicious .env files in HOME directory
• SSH directory permissions

🛠️ Developer Tools

• Docker, Kubernetes CLI, Terraform, Ansible
• Build tools (Make, CMake, GCC, Clang)
• Editors (VS Code, Cursor, Vim, Nano)
• CLI tools (gh, jq, ripgrep, fd, fzf, bat, eza, delta, lazygit, tmux, htop)

📁 Project Structure

devdoctor/
├── devdoctor.py        # Main script (single file, zero deps)
├── bin/
│   └── devdoctor       # CLI entry point
├── pyproject.toml      # Package configuration
├── README.md
├── LICENSE
└── .gitignore

🤝 Contributing

1. Fork the repo
2. Create your feature branch: git checkout -b feature/amazing-check
3. Add your check function in devdoctor.py
4. Make sure it returns CheckResult objects
5. Commit and push: git commit -m 'Add amazing check'
6. Open a Pull Request

📄 License

MIT — see LICENSE for details.

---

Made with ⚡ by nadonghuang
_{If you find this useful, please give it a ⭐!}