GitHub - zkzkGamal/zkzkAgent: zkzkAgent is a powerful, privacy-focused local AI assistant designed to act as your intelligent system manager on Linux. Built on LangGraph and Ollama, it automates complex workflows, manages system processes, handles network tasks, and provides voice interaction capabilities—all while keeping your data on your machine.

Demo Video 1

Demo Video 2

chmod +x install.sh && ./install.sh

# Download and install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull the default model
ollama pull qwen3-vl:4b-instruct-q4_K_M

# For Ubuntu/Debian
sudo apt update
sudo apt install -y python3-pip python3-dev portaudio19-dev ffmpeg

# NetworkManager (usually pre-installed)
sudo apt install -y network-manager

_type: chat
input_variables:
  - home

messages:
  - role: system
    prompt:
      template: |
        You are a local AI assistant acting as a **system manager**.
        # ... customize your prompt here

from langchain_ollama import ChatOllama

llm = ChatOllama(model="qwen3-vl:4b-instruct-q4_K_M")  # Change model here

# Change from:
user_input = input("Enter your request: ").strip()

# To:
logger.info("Listening for voice input...")
user_input = voice_module()
if user_input is None:
    logger.info("No valid input detected. Please try again.")
    continue
logger.info(f"[USER]: {user_input}")

User: Find the file main.py
AI: [Searches and returns file path]

User: Find config file
AI: [Automatically tries *config* wildcard search]

User: Find all Python files in the project
AI: [Uses find_file with *.py pattern]

User: Read the readme file
AI: [Finds and displays README.md content]

User: Show me the contents of agent.py
AI: [Displays agent.py content]

User: Open main.py
AI: [Opens in default text editor using xdg-open]

User: Open setup.py in VSCode
AI: [Uses open_vscode tool to open in VSCode]

User: Create a new Python project called 'ai-bot'
AI: [Uses create_project_folder("~/", "ai-bot") → Creates new directory]

User: Create main.py in myapp with a hello world script
AI: [Uses write_file("~/myapp", "main.py", "print('Hello')") → Writes content]

User: Read the content of src/utils.py
AI: [Uses get_file_content("~/myapp", "src/utils.py") → Returns code content]

User: what files are in the current project?
AI: [Uses get_files_info("~/myapp", ".") → Lists files with metadata]

User: Empty the trash
AI: I'm about to perform 'empty_trash'. This will delete data permanently. Please confirm with 'yes' or 'no'.
User: yes
AI: [Empties ~/.local/share/Trash]

User: Clear temporary files
AI: I'm about to perform 'clear_tmp'. This will delete data permanently. Please confirm with 'yes' or 'no'.
User: yes
AI: [Clears /tmp directory]

User: Remove old_backup.tar.gz
AI: I'm about to perform 'remove_file'. This will delete data permanently. Please confirm with 'yes' or 'no'.
User: yes
AI: [Deletes the file]

User: Open youtube.com
AI: [Checks internet → Enables Wi-Fi if needed → Opens in browser]

User: Browse github.com
AI: [Verifies connectivity → Opens URL]

User: Check if I'm connected to the internet
AI: [Uses check_internet tool → Reports status]

User: Enable Wi-Fi
AI: [Uses nmcli to enable Wi-Fi]

User: Open the current project in VSCode
AI: [Launches VSCode with current directory]

User: Open /home/user/myproject in VSCode
AI: [Opens specified directory in VSCode]

User: Run the deploy script
AI: [Reads deploy_v2.sh → Analyzes options → Selects appropriate option → Runs in background]
AI: Deploy script started in background. PID: 12345. Logs are being written to deploy.log.

User: Kill the deploy script
AI: [Terminates process 12345]

User: Find all Python processes
AI: [Uses find_process tool with 'python']
AI: Found the following Python processes:
    - PID: 92550
    - PID: 92560
    - PID: 96142

User: List all running processes
AI: [Uses find_process to locate processes]

User: Kill the deploy script
AI: [Finds and terminates the background deployment process]

User: Stop process 12345
AI: [Terminates the specified process using kill_process]

User: Find the config file, read it, and open it in VSCode
AI: [Executes find_file → read_file → open_vscode in sequence]

User: Check internet and open the project documentation
AI: [Checks connectivity → Enables Wi-Fi if needed → Opens URL]

User: Search for Python best practices
AI: [Uses duckduckgo_search tool → Returns top 5 results with titles, descriptions, and URLs]

User: Find information about LangGraph framework
AI: [Searches web and presents results with clickable links]

User: Look up the latest news about AI agents
AI: [Executes duckduckgo_search("AI agents news", 5) → Displays formatted results]

User: What's the current date?
AI: [Uses run_command("date") → Returns current date and time]

User: Show me the current user
AI: [Uses run_command("whoami") → Returns username]

User: Check disk space
AI: [Uses run_command("df -h") → Returns disk usage information]

User: Show system information
AI: [Uses run_command("uname -a") → Returns kernel and system details]

User: Stop the frontend
AI: [Uses stop_frontend() → Terminates remote frontend process]
AI: Frontend stopped successfully. PID 12345 killed on remote server.

User: Kill the frontend deployment
AI: [Checks running_processes state → Uses stop_frontend() → Reports success]

zkzkAgent/
├── main.py                     # Entry point & CLI loop with logging
├── prompt.yaml                 # System prompt configuration
├── requirements.txt            # Python dependencies
│
├── core/                       # Core agent components
│   ├── __init__.py
│   ├── agent.py                # LangGraph agent logic & graph definition
│   ├── state.py                # AgentState TypedDict definition
│   └── tools.py                # Tool exports & registration
│
├── models/                     # AI Model configurations
│   ├── LLM.py                  # Ollama LLM setup (qwen3-vl)
│   ├── voice.py                # Whisper model for voice input
│   └── tts.py                  # Coqui TTS for voice output
│
├── modules/                    # Auxiliary modules
│   └── voice_module.py         # Voice input processing with VAD
│
└── tools_module/               # Tool implementations (25 tools)
    ├── __init__.py
    │
    ├── files_tools/            # File operation tools (8 tools)
    │   ├── findFile.py         # Search for files with wildcards
    │   ├── findFolder.py       # Search for directories
    │   ├── readFile.py         # Read file contents
    │   ├── openFile.py         # Open files with xdg-open
    │   ├── getFileContent.py   # Read code files (coding tool)
    │   ├── writeFile.py        # Write code files (coding tool)
    │   ├── getFileInfo.py      # List file metadata (coding tool)
    │   └── createProjectFolder.py # Create project directories
    │
    ├── dangerous_tools/        # Tools requiring confirmation (3 tools)
    │   ├── __init__.py
    │   ├── emptyTrash.py       # Empty ~/.local/share/Trash/*
    │   ├── emptyTmp.py         # Clear ~/tmp/*
    │   └── removeFile.py       # Delete files/folders safely
    │
    ├── applications_tools/     # Application launchers (2 tools)
    │   ├── openVsCode.py       # Launch Visual Studio Code
    │   └── openBrowser.py      # Open URLs in default browser
    │
    ├── network_tools/          # Network management (4 tools)
    │   ├── checkInternet.py    # Verify connectivity (ping 8.8.8.8)
    │   ├── enableWifi.py       # Enable Wi-Fi using nmcli
    │   ├── networkSearch.py    # DuckDuckGo web search
    │   └── duckduckgo_search_images.py # Image search and download
    │
    ├── processes_tools/        # Process management (2 tools)
    │   ├── findProcess.py      # Find processes by name (pgrep)
    │   └── killProcess.py      # Terminate processes (SIGTERM)
    │
    ├── package_manager/        # Package management tools (3 tools)
    │   ├── detectOperatingSystem.py # Detect Linux distribution
    │   ├── installPackage.py   # Install system packages
    │   └── removePackage.py    # Remove system packages
    │
    ├── runDeployScript.py      # Deployment tools (2 tools: run_deploy_script, stop_frontend)
    └── runCommand.py           # System command execution (1 tool: run_command)

from langchain_core.tools import tool

@tool
def my_custom_tool(param: str) -> str:
    """Description of what this tool does."""
    # Your implementation
    return "Result"

from tools_module import my_custom_tool

__all__ = [
    # ... existing tools
    my_custom_tool.my_custom_tool,
]

DANGEROUS_TOOLS = ["empty_trash", "clear_tmp", "remove_file", "my_dangerous_tool"]

# Options: tiny, base, small, medium, large
whisper_model = whisper.load_model("small", device="cpu").cpu()

# Change speaker index (0-108 for VCTK model)
speaker = tts.speakers[11]  # Try different numbers

# Check if Ollama is running
ollama list

# Restart Ollama service
systemctl restart ollama

# Install NetworkManager
sudo apt install network-manager

# Enable and start service
sudo systemctl enable NetworkManager
sudo systemctl start NetworkManager

# Install PortAudio
sudo apt install portaudio19-dev

# Test audio devices
python3 -c "import sounddevice as sd; print(sd.query_devices())"

# Make deploy script executable
chmod +x ../deploy/deploy_v2.sh

# Check file permissions
ls -la ~/.local/share/Trash

# Install VSCode
sudo snap install code --classic

# Or via apt
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/trusted.gpg.d/
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update
sudo apt install code

# Install development dependencies
pip install -r requirements.txt

# Run tests
python3 tools_test.py