🚀 ARIA — AI Terminal Co-Pilot for Termux

Built for developers who use Termux as a real development environment on Android.

---

📋 Table of Contents

• About
• ✨ Features
• 🆕 Recent Improvements
• 📸 Screenshots
• 🎬 Demo
• 🚀 Quick Start
• 🔑 First Run
• 📖 Usage
• 🏗️ Architecture
• 🧠 Knowledge Base
• 🛡️ Safety Features
• 📊 Supported Models
• ⚙️ Configuration
• 🧪 Testing
• ⚠️ Limitations
• 🤝 Contributing
• 📄 License

---

About

ARIA is a terminal-native AI assistant designed specifically for Termux and Android development workflows. It combines Google's Gemma 4 models with a Termux-focused knowledge base, command system, and intelligent safety features to accelerate development on mobile devices.

Key Capabilities:

• 🤖 Intelligent code analysis and command fixing
• 🛡️ Guardian safety layer for command validation
• 📚 Offline knowledge base for Termux troubleshooting
• 👀 Watch mode for automatic error detection
• 💻 Rich terminal UI with syntax highlighting

Why ARIA?

Unlike generic desktop-focused coding assistants, ARIA understands the unique constraints of Android-based development:

⚙️ Clang instead of GCC 🗂️ Android filesystem quirks 🔒 Proot/container environments

📱 Mobile-only workflows 🚫 Package and permission limitations 🐛 Termux-specific debugging patterns

---

✨ Features

💻 Advanced Terminal UI Startup dashboard with visible slash commands Slash Command Interface (/ask, /fix, /provider, /model, /watch) Rich syntax highlighting & formatting Animated startup sequences Color-coded output	🤖 Intelligent AI Multi-provider model access Dynamic model discovery Auto model switching Self-healing API layer Graceful fallback handling
🛡️ Safety First Risk scoring system Confirmation prompts for dangerous operations Guardian safety layer Multi-level command validation	📚 Knowledge Base Common Termux errors Package management tips Python environments Proot-distro setup Android bridge tools
📋 Additional Features Clipboard Integration: Copy commands with one keystroke Watch Mode: Auto-detect and analyze terminal errors Offline Support: Works without internet for KB queries

---

🆕 Recent Improvements

• Better startup UX: ARIA now opens with a session dashboard that shows the active provider, model, safety state, watch state, and the most useful slash commands immediately.
• Faster provider switching: You can now switch directly with /provider google, /provider openrouter, or /provider nvidia_nim without going back through the full config wizard.
• Provider rotation: /provider cycle jumps to the next configured provider, which is useful when comparing output or working around a provider issue.
• Key management from the prompt: /provider key <name> updates or saves a provider key inline.
• Cleaner help output: /help, /provider list, and /model list now read like a control surface instead of raw debug text.

---

📸 Screenshots

📱 Click to expand screenshot gallery

Startup Interface

Model Selection

Error Analysis

---

🎬 Demo

lv_0_20260511165025-ezgif.com-video-to-gif-converter.mp4

---

🚀 Quick Start

Prerequisites

• Termux app on Android
• Python 3.8+
• Internet connection (for AI features)

Installation

# Update system packages
pkg update && pkg upgrade -y

# Install required tools
pkg install python git -y
pkg install termux-api -y

# Clone and install ARIA
git clone https://github.com/Alex72-py/aria-termux.git
cd aria-termux

# Install Python dependencies
pip install -r requirements.txt

# Launch ARIA
python run_aria.py

💡 Tip: termux-api is optional but recommended for clipboard integration. ARIA will gracefully fall back without it.

---

🔑 First Run

ARIA launches an interactive configuration wizard on first startup:

╔══════════════════════════════════════════╗
║  Welcome to ARIA Configuration Wizard    ║
╚══════════════════════════════════════════╝

Choose provider [google/openrouter/nvidia_nim]: google
Enter API key for provider: ••••••••••••••
Enter preferred model: gemma-4-26b-a4b-it
Enable Guardian mode? [y/n]: y

Get your free Google API key here:
🔗 Google AI Studio

---

📖 Usage

Startup Experience

After setup, ARIA shows:

• the active provider and model
• guardian and watch status
• a visible slash-command panel
• quick provider-switch shortcuts

Bare text is treated as /ask, so you can either type a command or just start talking to the model.

Command Reference

Command	Description	Example
/ask	Ask ARIA any question about Termux or development	/ask How do I install Python on Termux?
/fix	Analyze and fix terminal errors	/fix "clang: error: linker command failed"
/provider	Inspect or switch model providers	/provider openrouter
/model	Inspect or switch the active model	/model set google/gemma-3n-e4b-it
/models	List models for the current provider	/models
/kb	Search the offline knowledge base	/kb python module not found
/watch	Enable automatic error detection	/watch
/status	Show active provider, model, and safety state	/status

Provider Switching

Common flows:

/provider list
/provider google
/provider openrouter
/provider nvidia_nim
/provider cycle
/provider key openrouter
/model list

---

🏗️ Architecture

┌─────────────────────────────────────────┐
│           ARIA Core System              │
├─────────────────────────────────────────┤
│  📋 Command System                      │
│  ├─ /ask, /fix, /provider, /model      │
│  ├─ /models, /kb, /watch, /status      │
│                                         │
│  🤖 API Client                          │
│  ├─ Multi-Provider Routing              │
│  ├─ Auto Model Discovery                │
│  ├─ Intelligent Retry Logic             │
│  └─ Fallback Handling                   │
│                                         │
│  🛡️ Guardian Safety Layer               │
│  ├─ Risk Assessment                     │
│  └─ Confirmation Prompts                │
│                                         │
│  👀 Watch Mode                          │
│  ├─ Error Detection                     │
│  └─ Auto Analysis                       │
│                                         │
│  📚 Offline Knowledge Base              │
│  └─ Termux Troubleshooting              │
│                                         │
│  🎨 Rich Terminal UI                    │
│  ├─ Syntax Highlighting                 │
│  ├─ Animations                          │
│  └─ Color-Coded Output                  │
└─────────────────────────────────────────┘

---

🧠 Knowledge Base

ARIA includes comprehensive offline knowledge covering:

Category	Topics
🐛 Common Errors	Package conflicts, permission issues, build errors
📦 Package Management	pkg, apt, pip installation & troubleshooting
🐍 Python	Virtual environments, venv, pip caching
🐧 Proot-Distro	Linux distributions, container setup
🔌 Android Bridge	Termux:API, Tasker integration, system access
🔐 Git & SSH	SSH keys, Git configuration, GitHub access
🌐 Networking	Port forwarding, localhost, DNS issues

---

🛡️ Safety Features

Guardian Safety Layer

ARIA analyzes potentially dangerous commands before execution with a comprehensive risk assessment system:

Risk Level	Color	Description	Action
🟢 Low	Green	Safe operations (listing, viewing)	Execute immediately
🟡 Medium	Yellow	Network/code operations	Execute with notice
🟠 High	Orange	User/system modifications	Require confirmation
🔴 Critical	Red	Recursive deletion, destructive commands	Require explicit approval

---

📊 Supported Models

ARIA supports multiple providers:

Provider	Notes
google	Google AI Studio / Gemma access
openrouter	OpenAI-compatible multi-model routing
nvidia_nim	NVIDIA hosted model endpoints

Example Google Gemma family:

Gemma 4 Model Family
├── gemma-4-2b-it      (Lightweight, 2B parameters)
├── gemma-4-4b-it      (Balanced, 4B parameters)
├── gemma-4-26b-a4b-it (Advanced, 26B parameters)
└── gemma-4-31b-it     (Expert, 31B parameters)

Auto-discovery: ARIA fetches available models from the active provider automatically.

---

⚙️ Configuration

Config File

Configuration is stored locally in:

~/.aria/config.json

Example structure:

{
  "provider": "google",
  "api_key": "active-provider-key",
  "api_keys": {
    "google": "your-google-ai-studio-key",
    "openrouter": "your-openrouter-key",
    "nvidia_nim": "your-nvidia-key"
  },
  "model": "gemma-4-26b-a4b-it",
  "guardian_mode": true,
  "watch_mode": false,
  "max_tokens": 8192
}

Environment Variables

Override config with environment variables:

export ARIA_API_KEY="your-key"
export ARIA_PROVIDER="openrouter"
export ARIA_MODEL="gemma-4-31b-it"
export GOOGLE_API_KEY="your-google-key"
export OPENROUTER_API_KEY="your-openrouter-key"
export NVIDIA_NIM_API_KEY="your-nvidia-key"

---

🧪 Testing

Run the test suite with pytest:

# Run all tests
pytest -q

# Run with verbose output
pytest -v

# Run one test file
pytest tests/test_watch_mode.py -q

---

⚠️ Limitations

Development Status: This is a hackathon submission. These limitations are planned for future releases.

• 🔄 Watch mode is experimental and may require manual review
• 🌐 Internet connection required for AI features (knowledge base works offline)
• 📱 Optimized primarily for Termux on Android
• 🤔 Some auto-fix suggestions require manual verification

---

📦 Dependencies

Package	Purpose
google-generativeai	Google provider support
rich	Rich terminal formatting & UI
click	CLI command interface
pydantic	Data validation & models
python-dotenv	Environment variable management

See requirements.txt for versions and additional dependencies.

---

🤝 Contributing

We welcome contributions! Here's how to get started:

# Create a feature branch
git checkout -b feature/my-feature

# Make your changes and commit
git add .
git commit -m "Add my feature"

# Push and create a pull request
git push origin feature/my-feature

Guidelines:

• Follow PEP 8 for Python code
• Add tests for new features
• Update documentation
• Keep commits focused and descriptive

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 Alex72-py

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

---

🎯 Hackathon Submission

Submitted for: Google Gemma 4 Challenge

🏆 Highlights

• 🎯 Real-world Focus: Actual Termux developer workflow optimization
• 🔄 Dynamic Discovery: Auto-detect and switch between available models
• 🛡️ Resilient API: Self-healing with intelligent retry logic
• 📱 Mobile-First: Terminal UI optimized for small screens
• 💾 Offline Ready: Fallback support without internet connection
• 🔐 Safety-Conscious: Risk assessment before executing commands

---

🚀 ARIA

Making Android terminal development faster, safer, and more usable.

⬆ back to top