EnvDiff

Stop debugging "works on my machine" — forever.

Capture. Compare. Diagnose. Fix.

AI-powered environment diagnostics that finds the root cause in under 2 minutes.

---

The Problem · User Workflow · 3 Ways to Use · CLI · Web Dashboard · VS Code Extension · License

---

🛑 The Problem

Every developer has wasted hours on this:

"It works on my machine."

Your code runs perfectly. Your teammate's doesn't. Tests pass locally, fail in CI. The root cause is always hidden somewhere — a different Python version, a missing package, a forgotten environment variable.

EnvDiff solves this by capturing 11 dimensions of a machine in one command, diffing it, and using an AI Consensus Engine to output a copy-pasteable bash fix.

---

🗺️ User Workflow

Here is exactly how EnvDiff fits into your daily development cycle across all platforms:

flowchart TD
    A[Hit 'Works on my machine' bug] --> B(Install EnvDiff via pip)
    B --> C{Choose Your Workflow}
    
    C -->|Terminal Lover| D[1. CLI Tool]
    D --> D1["Capture Working Snap (envdiff capture)"]
    D1 --> D2["Compare Snaps locally (envdiff compare)"]
    D2 --> FIX[Get AI Root Cause & Bash Fix]

    C -->|Visual Debugging| E[2. Web Dashboard]
    E --> E1[Drag-and-Drop Working Snap]
    E1 --> E2[Drag-and-Drop Broken Snap]
    E2 --> E3[Run Multi-Persona AI Diagnosis]
    E3 --> FIX
    
    C -->|In-Editor Agent| F[3. VS Code Extension]
    F --> F1["Set Golden Base (Ctrl+Shift+P)"]
    F1 --> F2[Agent watches terminal for errors]
    F2 --> F3[Traceback Caught: 1-Click Auto-Fix]
    F3 --> FIX

Loading

---

🏗️ 3 Ways to Use EnvDiff

Before proceeding with any of the methods below, make sure your machine has Python and pip installed.

Pre-requisite: Getting pip

EnvDiff relies on the Python package manager pip.

• Check if you have pip: pip --version
• If missing: Run python -m ensurepip --upgrade or download Python from the official website (which automatically installs pip).

---

📦 Way 1: CLI (Terminal)

The standalone CLI is the foundation engine. Works purely offline—no server or browser required. Use it to simply snapshot your configuration and diff directly within bash/PowerShell.

1. Install EnvDiff CLI globally

pip install envdiff-ghosh

# Alternatively, install with hardware/resource detection:
pip install envdiff-ghosh[full]

2. Capture Environment (Working Machine)

To capture exactly what is functioning beautifully:

envdiff capture --label "my-golden-laptop"

This generates a JSON file (e.g. envdiff-snapshot-my-golden-laptop.json) storing 11 different vectors of data (packages, runtimes, OS, open ports, etc).

3. Capture Environment (Broken Machine)

Send the command to your teammate, have them run it:

envdiff capture --label "broken-teammate-pc"

4. Diff & Diagnose

Locally diff the two files entirely inside the terminal:

envdiff compare envdiff-snapshot-my-golden-laptop.json envdiff-snapshot-broken-teammate-pc.json

The CLI instantly outputs a colored terminal table highlighting Critical discrepancies, along with an AI-generated bash fix script.

---

🌐 Way 2: Web Dashboard

The web dashboard gives you a powerful visual interface, deep AI-powered diagnosis, comparison history, and shareable diff links.

Installation

1. Clone the dashboard:

git clone https://github.com/abhindn123/endiffffffff.git
cd endiffffffff

2. Setup Backend Server:

cd backend
python -m venv venv
source venv/bin/activate  # Or `venv\Scripts\activate` on Windows
pip install -r requirements.txt

# Start Server
python main.py

3. Setup Frontend Dashboard: (In a new terminal window)

cd frontend
npm install
npm run dev

Dashboard Workflow Guide

1. Navigate to http://localhost:5173 and click the Compare tab.
2. Upload Snapshot A (the JSON file from the working machine generated via CLI) and Snapshot B (the JSON file from the broken machine).
3. Run Diff to view the Neural Diagnostic Comparison.
4. Input Error: Paste the traceback/error you're seeing into the AI diagnose box. The AI consensus engine will output a precise Fix Script.

---

⚡ Way 3: VS Code Extension (Agent Mode)

Bring EnvDiff directly into your editor! The Agent automatically watches your editor's terminal for environment-related errors and injects one-click fixes.

Installation

1. Install CLI tool: You must install the cli tool globally first.

pip install envdiff-ghosh

2. Install the VSIX package:

code --install-extension vscode-ext/envdiff-agent-1.0.0.vsix

Alternatively, install from inside VS Code by opening the Extensions profile (Ctrl+Shift+X) -> ... Menu -> Install from VSIX and selecting the envdiff-agent-1.0.0.vsix file.

Agent Workflow Guide

1. Set the "Golden" Snapshot:
   • Ensure your code functions well under your present setup.
   • Press Ctrl+Shift+P (or Cmd+Shift+P on Mac).
   • Type and select EnvDiff: Capture Environment Snapshot.
   • Click the prompt to Set as Golden. This makes your current working setup the benchmark.
2. Hit an Error:
   • Imagine someone runs your repo, and hits a fatal terminal error like: ModuleNotFoundError: No module named 'flask'.
   • The EnvDiff VS Code Agent automatically parses the crash from the terminal traceback!
3. One-Click Auto-Fix:
   • A VS Code notification floats up indicating the missed dependency or environment drift.
   • Click the [Auto-Fix] button on the notification.
   • EnvDiff runs the background bash scripts needed within your terminal and entirely patches the environment for you. No Googling necessary!

---

🔄 GitHub Actions CI

Catch environment drift proactively by integrating EnvDiff into your CI/CD pipelines! Every time code is pushed, EnvDiff can snapshot the GitHub Action runner instance and verify it against your established golden snapshot.

Just place .github/workflows/envdiff-capture.yml into your project and save hours of failed pipeline builds. Any missing pipeline toolchains will be identified cleanly via Workflow artifacts!

---

🛠️ Tech Stack

Layer	Technology	Purpose
CLI	Python 3.7+, PyPI	Environment capture & offline comparison
Backend	FastAPI, Uvicorn, SQLite	REST API, diff engine, data persistence
Frontend	React 19, Vite 8	Interactive dashboard with terminal UI
Auth	Clerk	User authentication & session management
AI	Claude / GPT-4o / Gemini	Root-cause analysis & fix script generation
Extension	VS Code Extension API	Agent with error watcher + one-click fix
CI	GitHub Actions	Automated environment capture on every push

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

EnvDiff

The End of Environment Parity Issues

Start Building • Report Bug • Request Feature

^{Built by developers who are completely over debugging version mismatches.}