An ultra-lightweight, local agentic assistant for Android/Termux that controls phone hardware and parses queries in plain English. Powered by Cactus Compute's foundation models with full support for Needle 3 (new Laddered SAN architecture) and Needle 2 (legacy 14MB Core).
🌟 Features
- Dual Model Support (Needle 3 & Needle 2): Use the latest Needle 3 model for superior reasoning, sliceable depth, and grammar-constrained tool calling, or choose Needle 2 for the ultra-compact 14MB legacy core.
- Dynamic On-The-Fly Model Switching: Switch between Needle 3 and Needle 2 anytime via the Web UI header toggle, CLI commands, or Telegram bot messages without restarting the server.
- Interactive Chat Web UI: Sleek glassmorphic dashboard built using Flask for testing commands, toggling models, and monitoring live logs.
- Remote Telegram Bot Control: Start a background Telegram listener that lets you text your phone commands remotely and receive results instantly, with support for
/modelcommands. - Natural Language Translation: Translates commands like "turn on flashlight" or "tell me the battery status" to phone API calls.
- Hassle-Free Path Setup: Dynamically detects and prepends Termux binary folders (
/data/data/com.termux/files/usr/bin) to the environment path at runtime. - Desktop Simulator Mode: Simulated output layer allowing fully functional testing on Windows/macOS if run outside Termux.
📁 Project Structure
app.py: Flask Web Server hosting the Web UI + background Telegram bot listener + Model API.termux_needle.py: Lightweight interactive command-line assistant with model selector and dynamic switching.requirements.txt: Python package dependencies list (cactus-needle>=3.0.0).
🚀 Setup Guide
1. Prerequisites (on Android Phone)
Inside Termux, install the required packages:
pkg update && pkg upgrade
pkg install termux-api python git
pkg install proot-distro
proot-distro install ubuntu
proot-distro login ubuntu
Make sure you have the Termux:API app installed on your Android device.
2. Install Dependencies
apt update && apt upgrade -y
apt install git python3 python3-pip python3-venv -y
Clone this repository and install the dependencies:
git clone https://github.com/AbuZar-Ansarii/Needle.git
cd Needle
python3 -m venv myenv
source myenv/bin/activate
pip3 install -r requirements.txt
🧠 Selecting & Switching Models
You can choose whether to run Needle 3 (default) or Needle 2 across all modes:
1. Launch Interactive Web UI
Start the Flask server:
# Default (Needle 3)
python3 app.py
# Or launch directly with Needle 2
python3 app.py --model 2
Open your browser and navigate to:
http://127.0.0.1:5000
Tip: You can switch between Needle 3 and Needle 2 anytime by clicking the model toggle buttons in the top header of the web page!
2. Launch CLI Mode
Run the terminal-only interface:
# Interactive selection prompt at startup
python termux_needle.py
# Or specify your model explicitly
python termux_needle.py --model 3
python termux_needle.py --model 2
- Dynamic CLI Switch: Inside the assistant prompt, simply type
/model 2or/model 3to switch models instantly without closing the session.
3. Remote Telegram Bot Control
Launch app.py with the Telegram token:
python3 app.py --telegram YOUR_BOT_TOKEN
# Or specify a model at the same time:
python3 app.py --model 3 --telegram YOUR_BOT_TOKEN
- Remote Model Switch: Message
/modelto see the current model, or/model 2//model 3to change models remotely from Telegram.
No comments yet.