PocketStrike-AI

🧠 AI Agent that gives Termux a Brain

PocketStrike AI is a highly optimized, fully featured super lightweight AI agent core designed to bridge high-level reasoning with low-level Android/Linux device APIs. It is built to turn Termux into an autonomous system operator without bogging down your mobile device.

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 your phone’s 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 (which consumes 4GB+ RAM and drains battery in minutes), 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.
• 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, open Termux and run this single command to launch your dashboard:

cd ~/PocketStrike-AI && bash launch.sh

📂 Project Structure

📂 PocketStrike-AI/
├── 📄 LICENSE                # Open-source MIT License terms
├── 📄 README.md              # Detailed documentation, guides, and tool specifications
├── 📄 install.sh             # Dependency installer (Python, Git, Termux-API, Nmap, Curl, etc.)
├── 📄 launch.sh              # Terminal-based visual launcher dashboard and status check
├── 📄 server.py              # Main Flask server, AI ReAct framework, and Telegram bot loop
├── 📄 setup.py              # CLI Setup Wizard for API keys and Telegram bot options
├── 📂 static/                # Static assets for the Web chat interface
│   ├── 📄 script.js          # Web event handling, EventSource streaming, and markdown parsing
│   └── 📄 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 && sed -i 's/\r$//' install_linux.sh && bash install_linux.sh

Step 2: Launch the Linux Dashboard

Run the Linux visual launcher:

bash launch_linux.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 && sed -i '' 's/\r$//' install_mac.sh && bash install_mac.sh

Step 2: Launch the macOS Dashboard

Run the macOS visual launcher:

bash launch_mac.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!

🔌 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

• **Alwa