abuzar-ansarii/pocketstrike-ai

🧠 AI Agent that gives Termux, Linux, macOS & Windows a Brain

PocketStrike AI is a highly optimized, fully featured super lightweight AI agent core designed to bridge high-level reasoning with low-level device and operating system APIs. It runs seamlessly on Android (via Termux), native Linux distributions, macOS, and Windows (10/11).

It couples a gorgeous, responsive, glassmorphic chat interface with an advanced ReAct (Reasoning and Action) Function Calling Framework and native Model Context Protocol (MCP) support. This allows you to inspect system parameters, run subnet-wide network sweeps, execute background crons, dump active UI layouts for device automation, run sandboxed Python scripts, search the web using RAG, and connect to remote tool servers over SSE (Server-Sent Events).

Additionally, it integrates a Telegram Bot backend with unified session tracking, allowing you to trigger any of these system tools, check background schedules, or query your AI models remotely from your Telegram app.

⚡ Why is it Super Lightweight?

• Zero Local AI Inference Overhead: Instead of running massive, hot-running local LLMs on your mobile CPU or PC (consuming huge RAM and draining battery), PocketStrike AI acts as an intelligent orchestrator. It runs a lightweight ReAct state engine locally and delegates heavy token processing to remote API endpoints or local Ollama servers.
• Minimal Memory Footprint: The background Flask server is highly optimized, consuming only 30MB - 50MB of RAM under active loads.
• Ultra-Fast Vanilla Frontend: The user interface is crafted using Vanilla HTML, CSS, and JS (no heavy layout engines like React or Tailwind), loading instantly even on older budget Android phones or low-resource machines.
• Efficient Async I/O: High-speed utilities (like network sweeps and port scanners) run via custom parallel Python threads, completing sweeps in seconds with negligible CPU usage.

📋 System Requirements & Storage Footprint

---

🚀 Daily Quick Launch (One-Liner)

If you already completed the setup:

• Android (Termux): cd ~/PocketStrike-AI && bash launch.sh
• Linux: cd ~/PocketStrike-AI && bash linux/launch.sh
• macOS: cd ~/PocketStrike-AI && bash mac/launch.sh
• Windows: Double-click windows\launch.bat or run .\windows\launch.bat in PowerShell/CMD

---

📂 Project Structure

📂 PocketStrike-AI/
├── 📄 LICENSE                # Open-source MIT License terms
├── 📄 README.md              # Detailed documentation, guides, and tool specifications
├── 📱 install.sh             # Android Termux automated installer script
├── 📱 launch.sh              # Android Termux terminal visual dashboard launcher
├── 📁 linux/                 # Linux dedicated scripts (Debian/Ubuntu/Kali/Mint)
│   ├── 📄 install.sh         # Linux system & python installer script
│   └── 📄 launch.sh          # Linux visual dashboard launcher
├── 📁 mac/                   # macOS dedicated scripts (Homebrew / Apple Silicon & Intel)
│   ├── 📄 install.sh         # macOS system & python installer script
│   └── 📄 launch.sh          # macOS visual dashboard launcher
├── 📁 windows/               # Windows dedicated scripts (Windows 10/11)
│   ├── 📄 install.bat        # Windows batch installer wrapper (double-clickable)
│   ├── 📄 install.ps1        # Windows PowerShell dependency and environment installer
│   ├── 📄 launch.bat         # Windows batch launcher (double-clickable)
│   └── 📄 launch.ps1         # Windows PowerShell terminal dashboard launcher
├── 📄 server.py              # Main Flask server, AI ReAct framework, and Telegram bot loop
├── 📄 setup.py               # CLI Setup Wizard for API keys, providers, and bot options
├── 📂 static/                # Static assets for the Web chat interface
│   ├── 📄 script.js          # Web event handling, EventSource streaming, and UI logos
│   └── 📄 style.css          # obsidian-dark / royal-blue responsive layout stylesheet
└── 📂 templates/             # HTML Templates
    └── 📄 index.html         # Glassmorphic, modern chat dashboard interface

---

🛠️ Installation & Setup on Termux

Follow these steps to configure your Termux server:

Step 1: Install Git in Termux

Run this command to install git

pkg install git

Step 2: Clone and Run the Installer

Launch Termux and run this one-line command to install all basic dependencies (Python, Git, Flask, Requests, Termux-API, Nmap, Dnsutils, Curl, Net-Tools, Iproute2, and Traceroute):

git clone https://github.com/AbuZar-Ansarii/PocketStrike-AI.git && cd PocketStrike-AI && sed -i 's/\r$//' install.sh && bash install.sh

Note: During installation, the script will request Android Storage Permissions (termux-setup-storage). Tap “Allow” on the system popup.

[!TIP] Getting “CANNOT LINK EXECUTABLE” Error? This is a common Termux issue caused by a corrupted/outdated Termux environment (e.g. if installed from Google Play instead of F-Droid). Fix your Termux package manager by running:

apt update && apt full-upgrade

If Termux is completely locked, uninstall your current version and download the official updated build from F-Droid or GitHub Releases.

Step 3: Configure Setup Wizard

Run the launcher:

bash launch.sh

1. Select option 1 to run the Setup Wizard.
2. Select your AI provider and fill in the details:
   • Google Gemini (gemini-1.5-flash, gemini-1.5-pro)
   • OpenAI (gpt-4o, gpt-4-turbo, etc.)
   • Anthropic Claude (claude-3-5-sonnet, etc.)
   • Ollama (Auto-configures to http://localhost:11434 for offline local models like Llama3, Phi3, Gemma, etc.)
   • OpenRouter & Custom APIs (compatible with OpenAI format)
3. Select whether to enable Telegram Bot integration (requires your Bot Token and Chat ID).

Step 4: Run the Server

Choose option 2 from the launcher. Open the Local URL in your phone’s browser or the Network URL on your PC to start chatting!

---

🐧 Installation & Setup on Linux (Debian / Ubuntu / Kali / Mint)

PocketStrike AI also runs natively on standard Linux desktop and server distributions using apt package manager:

Step 1: Run the Linux Installer (One-Liner)

Open your terminal on Ubuntu, Debian, Kali, or Mint and run:

git clone https://github.com/AbuZar-Ansarii/PocketStrike-AI.git && cd PocketStrike-AI && bash linux/install.sh

Step 2: Launch the Linux Dashboard

Run the Linux visual launcher:

bash linux/launch.sh

1. Select option 1 to run the Setup Wizard (Configure AI keys, model provider, and Telegram bot options).

---

🍎 Installation & Setup on macOS (Apple Silicon & Intel)

PocketStrike AI runs natively on macOS (macOS 12+ / Sequoia / Sonoma / Ventura) using Homebrew:

Step 1: Run the macOS Installer (One-Liner)

Open Terminal on your Mac and run:

git clone https://github.com/AbuZar-Ansarii/PocketStrike-AI.git && cd PocketStrike-AI && bash mac/install.sh

Step 2: Launch the macOS Dashboard

Run the macOS visual launcher:

bash mac/launch.sh

1. Select option 1 to run the Setup Wizard.
2. Select option 2 to start the PocketStrike AI Server.
3. Open http://localhost:5000 in Safari or Chrome!

---

🪟 Installation & Setup on Windows (Windows 10 / 11)

PocketStrike AI runs natively on Windows 10 and Windows 11 with full PowerShell integration, native SAPI text-to-speech, system notifications, memory diagnostics, and stateful shell execution:

Step 1: Clone the Repository

Open PowerShell or Command Prompt:

git clone https://github.com/AbuZar-Ansarii/PocketStrike-AI.git
cd PocketStrike-AI

Step 2: Run the Windows Installer

Run the installer script (or simply double-click windows\install.bat in File Explorer):

.\windows\install.bat

Or directly in PowerShell:

powershell -ExecutionPolicy Bypass -File .\windows\install.ps1

Step 3: Launch the Windows Dashboard

Launch your visual terminal dashboard (or double-click windows\launch.bat):

.\windows\launch.bat

1. Select option 1 to run the Setup Wizard (choose your AI provider, model, API keys, and voice settings).
2. Select option 2 to start the PocketStrike AI Server.
3. Open http://localhost:5000 in Edge, Chrome, or Firefox!

---

🔌 Model Context Protocol (MCP) Integration

PocketStrike AI natively supports the Model Context Protocol (MCP) using the HTTP/SSE (Server-Sent Events) transport. This turns your Termux AI agent into an MCP Client, enabling it to dynamically load, query, and run tools hosted on remote servers (e.g., your PC, local network, or cloud).

How to Connect a Remote Server:

1. Host Binding: Start your MCP server on the host machine. To allow connections from your phone, ensure you bind it to 0.0.0.0 (all network cards) and select the SSE transport.
   • Example running a Python FastMCP script:

     fastmcp run --host 0.0.0.0 --transport sse your_script.py
     

2. Retrieve PC IP: Locate the host PC’s local IP address (e.g., 192.168.11.131).
3. Register on Dashboard: Open the PocketStrike Web UI on your phone:
   • Tap the + button in the MCP Connections section of the sidebar.
   • Provide a Server Name (e.g., dice-roller).
   • Enter the SSE Endpoint URL (e.g., http://192.168.11.131:8000/sse).
4. Automatic Handshake: PocketStrike AI will establish an active SSE stream connection, perform the official initialize/initialized protocol handshake, fetch the available tools, and automatically inject the remote tool schemas directly into the AI’s instruction set.
5. Real-time Execution: When the AI runs a remote tool, the request is wrapped in a standard JSON-RPC 2.0 structure, POSTed over the Wi-Fi network, and the result is returned live to the chat thread!

---

🎙️ Always-On Voice Assistant (“Hey Strike”)

PocketStrike AI features a background voice assistant that allows phone-wide, hands-free interaction:

• Background Wake-Word Listener: Simply say “Hey Strike”, “Strike”, or “Hey Pocket Strike” while watching movies, playing games, or using any app on your phone.
• Auto Tool Execution & Speech Response: The AI processes your spoken query, executes system/network/automation tools, and speaks the answer aloud using Android Text-To-Speech (termux-tts-speak).
• Heads-Up Screen Banners: Displays a lockscreen / notification card with the response directly over your active app.
• Web UI Voice Mode: Tap the glowing mic button in the top-right header of the Web UI to enable continuous hands-free voice mode with automatic browser SpeechSynthesis read-back.

---

✨ Features

• Always-On Background Voice Assistant (“Hey Strike”): Hands-free background voice listener daemon running in Termux that detects wake word “Hey Strike” while watching movies or using other apps, processes commands via the ReAct agent, and speaks answers back aloud via Android TTS & lockscreen notification cards. Also features Web Speech API Voice Mode in the Web UI.
• Unified Chat History Engine: The agent maintains a single unified mind across platforms. Messages sent via Telegram are instantly visible in the Web interface, and vice-versa, synchronizing context in real-time.
• 60-Message sliding window: Supports deep conversation tracking by passing up to the last 60 message states to the LLM API, while preserving complete logs on local storage.
• Self-Evolving Long-Term Memory: The AI dynamically updates agent/user.md, agent/memory.md, and agent/agent.md files via background conversation reflections. These files are re-injecting on every turn to adapt to your preferences.
• Active Threat Intrusion Sentinel: Runs a background daemon thread that checks /proc/net/arp and network metrics for active ARP Spoofing/MITM threats, automatically sending system lockscreen banners (via termux-api notification), text-to-speech warnings, and Telegram bot alerts.
• Rich Media Chat Previews: The Web UI automatically renders dynamic, cached-busted images () and video players () inside chat bubbles whenever workspace screenshots, photos, or recordings are generated or mentioned.
• Self-Dependency Doctor & Auto-Installer: Runs a full environment diagnostic (check_system_health) checking for required CLI utilities and Python modules, and can automatically execute non-interactive pkg install and pip install repairs if requested.
• Persistent Background Scheduler: A daemon thread checks for scheduled reminders or recurring cron intervals (e.g. “remind me to blink my eyes every 1 minute”) and alerts you locally or via Telegram.
• Audio Beep & System Fallback: If the device lacks Termux:API, the scheduler utilizes the ASCII Bell code (\a) to beep/vibrate Termux natively, and dynamically redirects screen alerts to Telegram.
• Robust ADB/Shizuku execution: Features parameter-safe parsing and automatic standard ADB fallbacks if the Shizuku emulator binder (rish) becomes unauthorized or goes offline.
• Web & Network Security Auditors: Built-in scanners to detect active Wi-Fi Man-in-the-Middle (ARP Spoofing) attacks, audit VPN connection leaks, and evaluate SSL certificates and HTTP security headers.
• Stateful persistent Terminal Session: Maintains directory changes (cd) and environmental variables across multiple command runs, operating inside a persistent background shell.
• Subnet-Wide Network Sweeps: Scans class C subnets (1-254) in less than 3 seconds using 80 parallel workers, resolving device hostnames automatically.
• Parallel Port Scanner: Checks up to 100 ports concurrently on local hosts using thread pools, automatically identifying active service names (SSH, HTTP, Database, etc.).
• Deep RAG Web Search: Scrapes DuckDuckGo HTML and automatically fetches the actual main body text of the top 2 web pages in the background. It feeds this text directly to the AI, bypassing knowledge cutoff limitations.

---

🛡️ Local Privacy & Self-Evolving Memory Core

PocketStrike AI is built with privacy-first principles. Zero conversation data is leaked to external cloud history trackers.

• Unified Conversation Log (unified_history.json): Your conversations are saved locally in a single private JSON database in your internal workspace, syncing Web chats and Telegram streams.
• Hermes-Style Persistent Memory Loop (Stored in agent/ sub-folder):
  • agent/user.md: Stores your profile, including your name, interests, skill levels, and specific user preferences.
  • agent/memory.md: Acts as your agent’s long-term memory. It logs system configurations, project conventions, tool tips, and lesson learnings.
  • agent/agent.md: Defines the agent’s soul, operational principles, tone of voice, and custom behavior directives.
  • These files are automatically loaded and re-injected into the system prompt on every turn. At the end of every user/assistant interaction turn (in both Web UI and Telegram), a background reflection thread evaluates the conversation changes and automatically appends/updates these files in real-time inside the agent/ subdirectory, keeping your main workspace clean and organized.

🔒 Security Sandbox Guardrails

• Path Enforcement: The AI is strictly sandboxed. All write/read operations normalize path traversals (..) and resolve absolute real paths. If the AI tries to write or modify anything outside of ~/storage/shared/PocketStrike-AI, the sandbox blocks it with an access denied error.
• Core Code Protection: Overwriting or modifying critical codebase files (like server.py, setup.py, launch.sh, etc.) is blocked by name, keeping the AI from corrupting its own server threads.
• Command Filter: execute_termux_command filters and blocks dangerous destructive tokens (such as rm -rf, rm -f /, mkfs, dd) to protect the device.

---

🔧 ReAct Function Calling Tools

PocketStrike AI has access to 76 built-in local tools to audit, crawl, and control systems:

[!IMPORTANT] Tools marked with [Requires Termux:API] require the Termux:API Android application (available on F-Droid) to be installed on your device, along with the CLI package (pkg install termux-api) configured inside Termux.