Hello everyone! 
I’d like to share an open-source project I’ve been developing for our community: **SysPilot**.
It is an agentic AI desktop workflow and system health sentinel designed specifically for Arch Linux and derivatives (EndeavourOS, CachyOS, etc.), built on top of [Goose AI](https://github.com/block/goose)
and my battle-tested local diagnostic suite (`sys-health`).
**GitHub Repository:** [https://github.com/Gbur79/SysPilot\](https://github.com/Gbur79/SysPilot)
Why SysPilot? (The “Token-Lean” Philosophy)
Most of us in the Linux community are rightfully skeptical of generic AI assistants. When a generic LLM is asked *“Why is my system failing to boot?”* or *“Why is my audio stuttering?”*, it usually:
- Spends tens of thousands of tokens dumping raw logs (`dmesg`, `journalctl`),
- Hallucinates obsolete Ubuntu tutorials from 2017,
- Suggests dangerous or destructive commands like blind `sudo rm` or broken partial upgrades.
**SysPilot flips this model completely on its head:**
```text
┌─────────────────────────────────────────────────────────┐
│ STEP 0: Local Triage Engine │
│ (0 tokens / 0 cost / 100% Deterministic) │
│ Scans repo/core updates, failed systemd units, │
│ .pacnew conflicts, disk space, and GameMode state. │
└────────────────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ STEP 1: Embedded SRE Playbooks │
│ (0 tokens / Verified Engineering Knowledge) │
│ FAF runner setup, Proton GE, PipeWire, .pacnew triage │
└────────────────────────────┬────────────────────────────┘
│
Only when complex deduction or reasoning is needed
▼
┌─────────────────────────────────────────────────────────┐
│ STEP 2: Goose AI SRE Copilot │
│ (Surgical context: ~400 - 900 tokens) │
│ Model receives pre-filtered root causes, not dumps. │
│ Cost: $0.0001 | Latency: ~1.5s │
└─────────────────────────────────────────────────────────┘
```
The underlying `sys-health` engine was built from real-world issues I personally encountered and by studying common failure patterns reported right here on the EndeavourOS forums—broken transactions, stale
pacman locks, kernel/initramfs desyncs, proprietary driver quirks, and tricky `.pacnew` merges.
Key Features
- **Zero-Sudo Boot Triage (<1s execution):**
- Checks official repos (`checkupdates`) and AUR packages without root privileges and without locking `/var/lib/pacman/db.lck`.
- Distinguishes **Core System Updates** (kernel, systemd, dracut, grub, mesa, nvidia) from regular packages.
- Detects un-rebooted kernel updates and `.pacnew` conflicts.
- **Smart GameMode Inhibit (Zero FPS Stutter):**
- Automatically detects active gaming sessions via Feral GameMode (`gamemoded` / D-Bus).
- Pauses all background scans, disk I/O, and desktop notifications while you game.
- **Dedicated System Maintenance Suite:**
- Interactive 3-tier orphan package resolver (safely purges abandoned packages while protecting `optdepends`).
- Regional mirror ranking with an atomic fallback gate (prevents truncating `mirrorlist` to 0 bytes).
- Safe package cache trimming (keeps latest 2 versions) and journal vacuuming.
- Deep clean for user trash, browser caches, and thumbnails.
- **Embedded SRE Copilot & Playbooks:**
- Comes preloaded with deterministic playbooks (PipeWire audio recovery, Steam 32-bit Vulkan/Proton readiness, `.pacnew` reconciler, Dracut/EFI recovery).
- **The FAF Miracle:** If you’ve ever tried setting up the **Forged Alliance Forever (FAF)** client on Arch, you know how painful orchestrating the Java runner, Proton GE, Steam Runtime container, and `G
ame.prefs` synchronization can be. SysPilot automates and repairs the entire setup in seconds.
- **Full Transparency (SRE Skill & Persona Tab):**
- You can inspect the exact telemetry JSON the agent sees before spending a single token.
- **Your Rig, Your Rules:** An editable text box lets you add custom directives (e.g., *“Prefer paru over yay”*, *“Desktop is Hyprland on Wayland”*, *“External DAC is Focusrite”*), which are permanently
saved and respected by the Copilot.
- **Layman-Friendly 30-Second AI Onboarding:**
- No terminal configuration or YAML editing needed.
- On first launch, a graphical wizard lets you select your provider (Google Gemini, OpenAI, Claude, or local offline Ollama) and paste your API key.
- *Recommendation:* I personally use **Google Gemini 3.8 / 2.5 Flash** (via Google AI Studio). It offers a generous free tier (no credit card required), sub-2-second latency, and is extremely token-effic
ient.
How to Install & Run
1. Install prerequisites:
```bash
sudo pacman -S --needed git python python-pyqt6 pacman-contrib jq libnotify
```
*(Optional for AUR updates:* `yay` or `paru`*)*
2. Install Goose CLI:
SysPilot uses the open-source Goose CLI as its sandboxed execution engine:
```bash
Via official installer:
curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash
Or via AUR:
yay -S goose-cli
```
3. Clone and launch SysPilot:
```bash
git clone https://github.com/Gbur79/SysPilot.git
cd SysPilot
Launch the Graphical Dashboard & System Tray sentinel:
./bin/syspilot
```
CLI Fast-Paths (For Terminal Enthusiasts):
You don’t even have to open the GUI to get an instant system scorecard:
```bash
Instant formatted terminal health scorecard (0 tokens, <0.8s):
./bin/syspilot -s
Ask the Copilot a direct question:
./bin/syspilot --copilot “Why is my audio crackling on PipeWire?”
Inspect active SRE skill directives & loaded playbooks:
./bin/syspilot --skill
Guarded system upgrade:
./bin/syspilot -u
```
Community Feedback Wanted
*Disclaimer: SysPilot is an independent, open-source community project and is not officially affiliated with the EndeavourOS development team or Block Inc. (Goose).*
Please give it a spin, test the dashboard or CLI triage, and let me know what you think—no need to mince words! Whether it’s edge cases with your bootloader setup, desktop compositors, or playbooks you’d lo
ve to see added, all feedback and PRs are warmly welcome.
**GitHub:** [https://github.com/Gbur79/SysPilot\](https://github.com/Gbur79/SysPilot)
Fly safe! 