Vinit Chaurasia

Posted on Oct 4

I built my friend Avijit an AI terminal doctor — because he was losing his mind over version mismatches

#devchallenge #weekendchallenge #hf26challenge #opensource

Hacktoberfest Weekend Challenge: Build for a Friend Submission 🤝

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

Who I Built This For: My Friend Avijit

My friend Avijit is a genuinely talented developer — smart, curious, and willing to grind through tough logic. But almost every week, I would get a frantic late-night call:

"Bhai, the terminal is throwing red errors and nothing makes sense. The command just refuses to run."

He wasn't struggling with algorithms or business logic. He was struggling with his environment.

Just last week, I watched him lose over two hours debugging a bizarre SyntaxError: Unexpected token '.'. It wasn't bad code — he had Node 14 installed globally, while his project required Node 18. The terminal didn't tell him "wrong Node version"; it just threw a cryptic wall of stack traces. He was convinced his code was broken and was ready to rewrite the entire feature from scratch.

Another time, his backend service failed because pip freeze showed fastapi==0.68.0 in his global environment, but his project's requirements.txt strictly required >=0.100.0. He had no idea those two states were clashing or which Python binary his active terminal was executing.

This is the "Avijit Problem" — but honestly, almost every developer has lost hours to mismatched dependencies, orphaned background processes hogging ports, or silent runtime version incompatibilities.

I wanted to fix this once and for all. So I built him his own terminal doctor.

What I Built

Framework Magnifier — an open-source AI terminal doctor and system diagnostician.

It is a fast, lightweight CLI that inspects running processes, open network ports, and multi-language dependency manifests. When something breaks, it translates cryptic errors and version conflicts into clear, actionable English instructions with a cyber-inspired neon HUD.

The Demo

1. Instant System & Process Inspection

python3 magnifier.py           # Top 10 processes by CPU
python3 magnifier.py --mem     # Top 10 processes by RAM

     PID │   CPU% │ Memory (MB) │ Username     │ Process Name
────────┼────────┼─────────────┼──────────────┼────────────────
       0 │    0.0 │         0.0 │ root         │ kernel_task
       1 │    0.0 │         0.0 │ root         │ launchd
     511 │    0.0 │         0.0 │ root         │ logd
     766 │    0.0 │       626.3 │ vinitchaurasia │ Antigravity IDE Helper
   99611 │    0.0 │       477.6 │ vinitchaurasia │ Google Chrome Helper

2. Ask the AI: "What is this process doing?"

python3 magnifier.py 1248

"This is a Node.js process (Webpack dev server) running from /home/avijit/projects/web-app. It is safe, but currently consuming high CPU — check if a hot-reload watcher is stuck in a loop."

Avijit's first reaction: "Wait, it can actually inspect and tell me that without me googling the PID?"

3. Port Conflict Detection & Inspection

python3 magnifier.py --ports
python3 magnifier.py port 5432   # AI explains what is listening and if it is safe to restart

   Port │      PID │ State      │ Process Name
─────────┼──────────┼────────────┼────────────────────────────
   3000 │    50686 │ LISTEN     │ Python
   5000 │      991 │ LISTEN     │ ControlCenter
   7000 │      991 │ LISTEN     │ ControlCenter
   8000 │    96793 │ LISTEN     │ Python
   8080 │    19642 │ LISTEN     │ Python

4. The Game Changer: Multi-Language Dependency Doctor

python3 magnifier.py check-deps

It auto-detects and scans manifest files across your repo, queries the runtime environment, and highlights version drift:

"Found requirements.txt: requests >=2.31.0, but installed environment has requests==2.25.1. Run pip install --upgrade -r requirements.txt."

Supported ecosystems:

Python: requirements.txt, pyproject.toml
Node.js: package.json
Rust: Cargo.toml
Go: go.mod
Ruby: Gemfile
PHP: composer.json
Java: pom.xml, build.gradle

5. Seamless Command Execution & AI Diagnosis

Run risky terminal commands through Magnifier:

python3 magnifier.py run -- npm run build
python3 magnifier.py run -- cargo build

Or pipe failed command logs directly:

cargo build 2>&1 | python3 magnifier.py --errors

If a command fails, Gemma analyzes the stderr output, cross-references installed tooling versions, and gives a direct 3-step solution to fix it.

Code & Repository

GitHub Repository: chourasiavinit9-dev/framework-magnifier
CI / Workflows: Tested with GitHub Actions CI across macOS, Ubuntu Linux, and Windows for Python 3.10, 3.11, and 3.12.

Quick Start

git clone https://github.com/chourasiavinit9-dev/framework-magnifier.git
cd framework-magnifier
pip install -r requirements.txt
export GEMINI_API_KEY="your_api_key_here"  # Free tier via Google AI Studio
python3 magnifier.py

Docker Container (Zero-Install)

docker build -t framework-magnifier .
docker run --rm -it --pid=host -e GEMINI_API_KEY="your_key" framework-magnifier

Why Open-Source AI? Why Gemma?

I deliberately chose not to build this around a closed proprietary model. Here is why open innovation and open weights matter:

User Privacy & System Security: System diagnostics require reading process trees, open ports, and package configurations. Sending raw internal process tables or proprietary workspace manifests to third-party closed servers creates significant compliance and privacy risks. With open weights like Gemma-4, developers have complete agency over where data flows.
Predictable Free Access for Students: Avijit is a student. He can't afford pay-per-token meters or surprise credit card charges while debugging code. Google's generous open access via Google AI Studio ensures any developer or student can use this for free.
Model Swappability & Local Offline Use: Because Framework Magnifier is built on an open architecture, you are never locked into one provider. Users can switch models via environment variables or run completely air-gapped and offline using Ollama:

export MAGNIFIER_MODEL="gemma-4-26b-a4b-it"

How It Solved It for Avijit

I sent the first build to Avijit over the weekend. Within twenty minutes, he messaged me:

"Bro, it immediately flagged that my terminal was executing Python 3.9 from an old Homebrew symlink while my project virtual environment was expecting Python 3.11. I spent three hours banging my head against the wall on this last week."

Seeing him run python3 magnifier.py check-deps and immediately unblock himself made the entire project worth building.

Prize Categories

Best Use of Gemma ($200 Featured Track): Framework Magnifier relies directly on Google's open-weight Gemma-4 model family to power intelligent system reasoning, process introspection, multi-language version drift identification, and automated command stderr triage without telemetry leaking to closed commercial models.
Overall Hacktoberfest Challenge: Built from scratch during the hackathon window specifically for a real friend (Avijit) solving an everyday developer barrier using open-source AI.

Agent Session & Build Transcript

Framework Magnifier was designed and developed with pair programming assistance via DevRelay and Google Antigravity. Explore the interactive transcript below to see the reasoning, testing, and tool calls:

Building Framework Magnifier: AI Terminal Doctor with Gemma-4

You

I want to build an open-source AI terminal doctor for my friend Avijit who struggles with mismatched dependencies, orphaned processes, and cryptic terminal errors. It should monitor system processes, open ports, and diagnose dependency mismatches across multiple languages using Google Gemma-4.

Agent

Let's architect Framework Magnifier using Python, psutil for system telemetry, and Google Gemma-4 for root-cause diagnosis. We will implement CPU/RAM inspection, port conflict scanning, multi-language manifest analysis (requirements.txt, package.json, Cargo.toml, go.mod, pom.xml), and automated command failure triage.

You

Add high-contrast neon HUD styling and error badges so errors are immediately highlighted in bright red, warnings in yellow, and safe states in neon green.