zkzkAgent v3 – now with safe, conflict-aware package management

Managing Linux is powerful but exhausting. Remembering exact commands, hunting down files, killing rogue processes, checking network, deploying scripts — it adds up fast.

What if you had a local AI that doesn’t just tell you what to do — it actually executes safely, with your approval every time anything dangerous happens?

That’s why I built zkzkAgent — fully offline, no cloud, no telemetry, privacy-first Linux system manager.

Repo → https://github.com/zkzkGamal/zkzkAgent

🚀 What’s Working Really Well

🛠 1. Real System Control
zkzkAgent can:

• Search files & folders intelligently
• Find & kill processes
• Run safe shell commands (ls, date, whoami, etc.)
• Deploy scripts with AI help choosing options
• Handle all destructive actions (rm, install, remove) with explicit human confirmation

It reads your intent, plans the safest path, and streams results live.

🌐 2. Network Smarts

• Auto-checks internet before any web/search/browser task
• Reconnects Wi-Fi via nmcli if dropped
• Searches DuckDuckGo or grabs images straight to your media folder

Makes remote work, quick lookups, and downloads seamless.

🎤 3. Optional Voice Mode

• Whisper for speech-to-text
• Coqui TTS (working on XTTS-v2 cloning for better anime-ish voices)
• Hands-free control — talk to your system like a real assistant

Type or speak — it responds either way.

🔥 New: Smart Package Management (the part I’m most excited about)
Just added a package tool that actually feels safe & useful for developers:

• Human-in-the-loop on every install/remove/upgrade/clean
• Detects OS once → uses safe priority to avoid dependency hell:
  1. Special cases (no search needed):
     • postman → sudo snap install postman
     • code/vscode → sudo snap install --classic code
     • discord/slack → snap or flatpak
     • zoom → wget .deb + dpkg
  2. Flatpak first for GUI/dev tools (sandbox + shared runtimes = fewer fights)
  3. Snap next
  4. apt only for CLI/system utils
• Checks if already installed (command -v / snap list / flatpak list) before suggesting
• Shows full command preview + explanation (dry-run style)
• Logs every command + your approval
• No blind runs — always "yes/no" for anything that touches the system

Example flow — "install postman":

→ planner sees snap path
→ executor: check_internet() once → propose "sudo snap install postman"
→ shows preview → waits for "yes"
→ runs → verifies with postman --version

Why this matters for devs:

• Avoids the classic "apt install nodejs → wrong/old version" nightmare
• Reduces snap vs flatpak vs apt version conflicts (huge pain on Ubuntu)
• Everything is auditable — you see exactly what ran

🧠 How I Built It

• LangGraph → stateful agent graph (planner → executor → tools → human interrupt)
• Ollama → local inference (Llama 3.1 8B or whatever model you run)
• Tools → simple Python wrappers (subprocess for shell, etc.)
• Safety → interrupt + input() for confirmation on dangerous actions

Everything 100% local — no data leaves your machine.

🧪 Honest Limitations Right Now

• Only tested on Ubuntu/Debian (apt/snap/flatpak paths)
• No automatic rollback if install fails (yet)
• Voice TTS prosody still needs work (switching to XTTS-v2 cloning soon)
• Package tool is smart but not perfect — edge cases exist

Quick Start (try it in ~2 minutes)

git clone https://github.com/zkzkGamal/zkzkAgent.git
cd zkzkAgent
chmod +x install.sh
./install.sh
source venv/bin/activate
python main.py

Then just type:

"install postman"
"install discord"
"check node version"
"find all python files in my project"
"kill firefox"

🎯 Looking for Dev Feedback

Better conflict detection? (e.g. dpkg -s / snap list before proposing apt?)
Should it auto-suggest nvm/pyenv/volta for node/python/go runtimes?
Flatpak vs snap — which should be default for GUI apps in 2026?
Any scary package edge cases I missed? (PPA hell, broken deps, etc.)

PRs, issues, forks, brutal roasts — all welcome.
Built in Cairo with ❤️ by zkaria (@zkzkgamal11)

This version keeps your voice: honest, technical enough for devs, shows real value, admits limitations, and invites collaboration — just like your original example.

Let me know if you want it shorter, more code-heavy, or tweaked for a specific platform (X thread, Reddit, DEV.to, etc.). Ready to ship! 🚀