Inspiration
As generative AI advances, developers face a critical design question: how do we harness AI assistance for system administration without handing over dangerous, autonomous control of the underlying OS?
We were inspired to build a tool that bridges this gap—a diagnostic CLI copilot that can classify requests, explain resource usage, and provide visual guidance, while enforcing a disciplined boundary against automated or dynamic system change
What it does
linux-health-copilot is a CLI diagnostic tool. Running locally on your machine, it inspects key system metrics (specifically memory usage and running processes) and uses the Gemini AI API to translate raw output into clear, actionable human explanations. Crucially, it enforces a strict fail-closed security boundary: no local diagnostic command runs without explicit user approval, and destructive actions (like process termination) are restricted entirely to color-coded, manual-only visual advice.
How we built it
The application is built in Python 3.10+ using the official google-genai SDK (gemini-3.5-flash-lite) and python-dotenv. We implemented a strict separation of concerns between local system execution and remote AI interpretation: 🐍 Python (The Enforcer & Executor)
Enforces a hardcoded allowlist of safe diagnostic commands (free, ps).
Defends against command injection by invoking local subprocesses exclusively with shell=False and fixed argument arrays.
Manages an interactive [y/N] confirmation gate that defaults to fail-closed (N).
Handles all system actions locally—Python never passes model-generated text or external strings to a subprocess, ensuring state-changing suggestions (like kill <PID>) remain strictly manual visual guidance.
✨ Gemini AI (The Classifier, Interpreter & Advisor)
Operates via the remote gemini-3.5-flash-lite endpoint.
First classifies initial user requests upfront to determine the appropriate diagnostic or guidance path before any system interaction begins.
Subsequently receives pre-approved raw output from local diagnostic commands (specifically memory and process metrics) to explain system states in plain English.
Suggests remediation steps as visual text advice for human review—it never triggers automated system modifications or local subprocess execution.
Challenges we ran into
The hardest challenge was designing a strict, reliable safety boundary while maintaining a helpful user experience. Giving an external API dynamic control over OS execution opens up real risks of command injection, hallucinated parameters, and accidental system disruption.
We addressed this by structuring Gemini's responsibilities across three clear roles: request classification upfront, post-execution memory and process output interpretation, and text-only remediation advice. Instead of letting the AI drive local execution, we leveraged Gemini for intent classification and safe metric interpretation, while keeping all execution logic hardcoded locally behind explicit human confirmation gates.
What we learned
Working with WSL, local Python subprocesses, and the Gemini API reinforced a vital principle for AI tooling: AI can classify, explain, and advise over API boundaries, but local execution must remain under deterministic, hardcoded software controls. True safety isn't just about prompt engineering; it's built into the architecture through strict local allowlists, explicit confirmation gates, and a fail-closed default mindset.
Log in or sign up for Devpost to join the conversation.