AbuZar-Ansarii/Needle
AI EngineeringA local Termux agent that turns plain-English requests into Android phone controls and offline queries.
Overview
Needle is a lightweight agentic assistant that runs inside Termux on Android. It accepts natural-language requests such as "turn on the flashlight" or "what is the battery percentage" and translates them into calls to Android hardware and system APIs. It also bundles a local knowledge base, an offline camera-document extractor, SMS/notification triage, and a Telegram bot for remote control.
The project wraps Cactus Compute's foundation models through the cactus-needle Python package. It supports two model options: Needle 3 (default) and the legacy 14 MB Needle 2 core. Both can be switched at runtime from the Web UI header, the CLI (/model 3 or /model 2), or Telegram messages, without restarting the server. The Web UI is a Flask app (app.py); a separate CLI (termux_needle.py) provides a terminal-only interface.
Quick Start
Run this on an Android device with Termux installed. Install the Termux:API app first so hardware calls have a bridge.
pkg update && pkg upgrade
pkg install termux-api python git
pkg install proot-distro
proot-distro install ubuntu
proot-distro login ubuntu
Inside the Ubuntu environment, install the Python dependencies and the repository:
apt update && apt upgrade -y
apt install git python3 python3-pip python3-venv ca-certificates -y
git clone https://github.com/AbuZar-Ansarii/Needle.git
cd Needle
python3 -m venv myenv
source myenv/bin/activate
pip3 install -r requirements.txt
This installs cactus-needle>=3.0.0 together with the Flask web server. The README notes that app.py and termux_needle.py sanitize inherited ANDROID_ROOT and ANDROID_DATA variables so the engine detects the ARM64 Ubuntu environment README setup steps.
Start the Web UI:
python3 app.py
Then open http://127.0.0.1:5000 in the phone's browser. Use python3 app.py --model 2 for the smaller model, or launch the CLI with python termux_needle.py. Telegram control requires a bot token: python3 app.py --telegram YOUR_BOT_TOKEN README model section.
Constraints
- The project targets Android/Termux with the Termux:API app installed; the README describes a desktop simulator mode for Windows/macOS, but its output layer is simulated and does not exercise real phone hardware.
- The setup requires installing a full Ubuntu PRoot environment in addition to Termux packages. The
cactus-needlepackage and its model downloads are external dependencies not included in the repository. - Many commands touch sensitive data and system permissions: SMS, call logs, contacts, clipboard, location, camera, microphone recording, and biometric prompts. These require the corresponding Android runtime permissions for Termux/API.
- No license is declared in the repository, so reuse and redistribution terms are unclear.
- The repository has no HotRepo snapshot or ranking history yet; no adoption or stability data is available.
HotRepo's take
The README is unusually broad: it claims flashlight, Wi-Fi, SMS, calls, contacts, camera OCR, a 3,072-dimension vector knowledge base, Telegram remote control, and dynamic model switching across two models project README. That breadth makes the Android permission surface large, and the two model sizes are presented without benchmarks or hardware timing. A short demo video is linked, but there is no measured evidence of latency or accuracy. Someone evaluating the project should check the cactus-needle dependency and its source separately, since the repository itself appears to be the wrapper rather than the model implementation.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
You might also like
- guzhou079-arch/deepseek-harness-androidAn Android APK that bundles DeepSeek Harness with screen automation, virtual display, scheduled tasks and 27 skills, without Termux or root.
- phone-harness/phone-harnessA Python CLI that lets coding agents tap, type, scroll, and read real iPhones or Android phones.
- ashhart/TensorFoldServe quantized LLMs natively on Apple Silicon and NVIDIA GPUs with an OpenAI-compatible API and no Python.
- browser-use/browser-usePython library that lets an LLM drive a real browser via CDP to complete web tasks.
- tapilot-ai/tapilotAn experimental Android app that executes plain-language phone tasks using a vision model and accessibility control.