CLI Github Challenge- #LinuxCompass

*This is a submission for the GitHub Copilot CLI Challenge*

What I Built

The Linux Compass

(linux-compass) is a safety-first command line interface (CLI) tool that acts as a "Guardrail" for your terminal. It wraps the GitHub Copilot CLI to translate natural language into shell commands, but adds a critical layer of safety and interactivity that raw AI output lacks.The Linux Compass is a battle-tested, safety-first CLI wrapper that supercharges the GitHub Copilot CLI. It transforms vague natural language into precise, immediately executable shell commands—while enforcing mandatory guardrails against catastrophic mistakes.

At its heart, it is a Python application (built with Typer and Rich) that:
Translates plain-English requests (e.g., "recursively find all .py files over 1MB and sort by size") into shell commands.

Queries the GitHub Copilot CLI (gh copilot suggest) for intelligence.

Parses the response through a custom "Noise Filter" engine to remove API warnings.

Detects Danger using a regex-based "Red Guard" system before ever showing the command.

Visualizes results in beautiful, color-coded interactive panels.

The Problem

For many developers, especially students or those new to DevOps, the terminal is a place of anxiety. We’ve all been there: staring at a blinking cursor, trying to remember the exact flags for tar or ffmpeg, terrified that one wrong keystroke might wipe a directory. While AI tools are great at suggesting commands, the "Copy/Paste" workflow is inherently risky. If Copilot suggests rm -rf ./, how do I ensure I don't run it blindly?

The Solution: A Compass, Not Just a Map

I built a tool that doesn't just "fetch" commands, but guides the user:

• Natural Language to Shell: Translates queries like "find all large python files" into complex find commands instantly.
• The "Red Guard" Safety System: This is the core feature. The tool automatically parses the AI's suggestion for high-risk keywords (like rm, delete, or recursive flags). If a dangerous command is detected, it forces a Safety Interruption with a bright red warning panel, preventing "autopilot" mistakes.
• Legacy Robustness: I built this on a Chromebook running a legacy Linux container. To make it work, I wrote a custom parsing engine that programmatically filters out API deprecation warnings and noise, ensuring the tool works even on older environments where standard tools might fail.

Tech Stack

• Python (Core Logic)
• GitHub Copilot CLI (Intelligence Engine)
• Typer (CLI Interface)
• Rich (UI/UX - Panels and Colors)

Demo

Source Code: https://github.com/walukrypt0/linux-compass

1. The "Happy Path" (Safe Command)

Here, I ask the compass to list files sorted by size. It returns a safe, green panel with the correct ls command.

2. The "Red Guard" (Safety Interruption)

Here, I ask to "delete all files." The Compass detects the danger in the underlying rm command and triggers the Red Warning system.

My Experience with GitHub Copilot CLI

Building a CLI tool using the Copilot CLI was a unique "meta" experience. I wasn't just using AI to write code; I was building infrastructure around the AI.

The "Chromebook Challenge"
My development environment was a major constraint. I built this entirely on a Chromebook in Lagos, Nigeria, dealing with network timeouts and legacy tool versions. At one point, version conflicts caused the CLI to output nothing but "Deprecation Warnings."
The gh-copilot extension was officially deprecated in late 2025. For developers on modern rigs, upgrading was easy. But for those of us on legacy hardware or constrained environments (like my locked-down Chromebook Debian container in Nigeria), the upgrade path was broken by mirror timeouts and dependency conflicts.

This is where the Copilot CLI shined. I used it to help me write the regex and string parsing logic needed to "clean" the output. It turned a blocking bug into a feature: now, my tool is robust enough to handle messy API responses that would crash other wrappers.

Screenshots

1. The Happy Path (Safe Execution) When the command is safe, the Compass gives you a green light. [INSERT SCREENSHOT OF GREEN SUCCESS PANEL]

2. The Red Guard (Danger Interception) When I ask to "delete all files," the tool intercepts the rm -rf command and blocks execution until I explicitly override it. [INSERT SCREENSHOT OF RED WARNING PANEL]

3. Defeating Deprecation Left: The raw, noisy output from the legacy CLI. Right: The Compass successfully extracting the valid command. [INSERT SCREENSHOT OF TERMINAL SPLIT VIEW IF AVAILABLE]

I refused to let that stop me. I used Copilot to help me write a Multi-Stage Resilience Engine:

Stage 1: Stream Capture I learned to capture both stdout and stderr simultaneously, as the deprecation warnings often leaked across streams.

result = subprocess.run(
    ["gh", "copilot", "suggest", "-t", "shell", query],
    capture_output=True, text=True
)
# Merge streams because warnings love stderr
raw_output = result.stdout + result.stderr

Stage 2: The Noise Filter I implemented a regex-based blacklist to surgically remove the "API noise" while preserving the shell command.

NOISE_PATTERNS = [
    r"deprecated", r"extension has been", r"migrate to", 
    r"visit https", r"github.blog", r"agentic"
]

clean_lines = [line for line in raw_output.splitlines() 
               if not any(re.search(pat, line, re.IGNORECASE) for pat in NOISE_PATTERNS)]

Stage 3: Context-Aware Safety Early versions naively flagged the word "Information" as a dangerous rm command. Copilot helped me refine the regex to be token-bound, ensuring we only flag actual destructive commands.
# The evolved safety check
DANGEROUS_REGEX = [
r"\brm\s+(-r|-rf|--recursive)\b",
r"\b(mkfs|dd|shred)\b"
]

CHALLEGES WE RAN INTO")
The biggest hurdle was Dependency Hell. Working from a resource-constrained environment meant I couldn't just "brew install" my way out of problems.

The critical moment came when I finally got the GitHub CLI working, only to be met with a wall of text: "The gh-copilot extension has been deprecated."

The Block: The warning text was confusing my "Safety Guard" logic. My code saw the word "Information" in the warning message, triggered on the letters "rm", and falsely flagged the warning itself as a dangerous file-deletion command!

The Pivot: I had to rewrite the safety logic to be context-aware (looking for rm followed by a space) and rewrite the fetch logic to ignore the warning entirely.

This wasn't just about writing a prompt; it was about handling dirty data in real-time. It forced me to understand Linux process piping (subprocess.run), stream handling, and robust string parsing.

Key Takeaways:

• AI as a Subprocess: Learning how to pipe stdout and stderr from the Copilot CLI into Python gave me a deeper understanding of Linux process management.
• Guardrails are Essential: Working with the CLI made me realize that while AI is smart, it lacks context. Adding the "Safety Check" layer in Python showed me how we can build responsible AI tools that trust, but verify.

This project transformed my terminal from a static black box into a conversational partner—one that I can now trust not to delete my entire project by accident!

Conclusion
GitHub Copilot CLI didn't just accelerate my coding; it taught me to treat AI output as untrusted input. It pushed me to build verification layers and engineer for the worst-case environment.

This project is my proof that powerful, safe tools can come from constrained places. Winning this challenge would be life-changing—offering the stability I need to support my family and go full-time on open-source DevOps security tools.

Let's make the terminal safer, together.