Skip to content

README.md

Latest commit

 

History

History
363 lines (253 loc) · 8.74 KB

README.md

File metadata and controls

363 lines (253 loc) · 8.74 KB

🚨 CRITICAL: This project requires 4 pre-compiled packages from Termux. DO NOT install them via pip:

pkg install python-grpcio python-pillow python-cryptography python-pydantic

Attempting to install these via pip will result in compilation failures.

🤖 Gemini CLI for Termux

Made for Termux Python 3.11+ License: MIT

A native, lightweight Gemini AI CLI built specifically for Termux on Android

Features • Installation • Usage • Configuration • FAQ

📢 About This Project

This project is inspired by and aims to provide similar functionality to the official Google Gemini CLI, but reimagined from the ground up for Termux on Android.

🙏 Credits

  • Inspired by: google-gemini/gemini-cli - Official Gemini CLI by Google
  • Built for: Termux community on Android
  • Purpose: Provide a working, native solution for Android users

Note: This is NOT a fork of the official repository. It's a complete rewrite in Python to solve Termux-specific compatibility issues. All credit for the original concept and design goes to the Google Gemini team.

🎯 Why This Exists

The official @google/gemini-cli doesn't work on Termux due to:

  • ❌ Native module compilation failures (node-pty, keytar, etc.)
  • ❌ Platform detection issues (Android not recognized)
  • ❌ Clipboard integration broken
  • ❌ OAuth2 authentication complexity

This project solves these issues by building a native Python solution specifically for Termux, while maintaining the spirit and functionality of the original CLI.

✨ Features

  • ✅ Zero Native Dependencies - Pure Python, installs instantly
  • ✅ Termux-Optimized - Built specifically for Android/Termux environment
  • ✅ Beautiful UI - Rich terminal interface with syntax highlighting
  • ✅ Clipboard Integration - Direct Termux-API support
  • ✅ Conversation History - Persistent chat sessions
  • ✅ File Analysis - Upload images, PDFs, and documents
  • ✅ Streaming Responses - Real-time AI output
  • ✅ Lightweight - Minimal resource usage, battery-friendly
  • ✅ Offline Config - No internet needed for setup

📦 Installation

Quick Install (Recommended)

# Install dependencies (INCLUDING 4 pre-compiled native libraries)
pkg update && pkg upgrade -y
pkg install python git termux-api python-grpcio python-pillow python-cryptography python-pydantic -y

# Clone repository
git clone https://github.com/Alex72-py/gemini-cli-termux.git
cd gemini-cli-termux

# Run installer
chmod +x install.sh
./install.sh

⚠️ CRITICAL: The following packages MUST be installed via pkg, NEVER via pip:

  • python-grpcio - gRPC library (C++)
  • python-pillow - Image processing (C)
  • python-cryptography - Cryptography (Rust)
  • python-pydantic - Validation (Rust)

These packages require native compilation (C++, C, Rust) which fails on Termux. Using pre-compiled Termux packages avoids all compilation errors.

Manual Installation

# Install Python packages
pip install --break-system-packages -r requirements.txt

# Install packages requiring native compilation (use Termux packages)
pkg install python-grpcio python-pillow python-cryptography

# Install google-generativeai (requires system grpcio)
pip install --break-system-packages --no-deps google-generativeai
pip install --break-system-packages google-ai-generativelanguage protobuf

# Install CLI
pip install --break-system-packages -e .

# Setup
gemini-termux setup

🚀 Quick Start

1. Get Your API Key

  1. Visit Google AI Studio
  2. Click "Create API Key"
  3. Copy your API key

2. Configure

# Run setup wizard
gemini-termux setup

# Or set manually
export GEMINI_API_KEY="your-api-key-here"

3. Start Chatting

# Interactive chat mode
gemini-termux chat

# Quick question
gemini-termux ask "What is Termux?"

# Analyze an image
gemini-termux chat --image screenshot.png

📖 Usage

Interactive Chat

gemini-termux chat

Commands in chat mode:

  • /exit or /quit - Exit chat
  • /clear - Clear conversation history
  • /history - Show conversation history
  • /copy - Copy last response to clipboard
  • /save - Save conversation to file
  • /model <name> - Switch model
  • /help - Show all commands

One-Shot Questions

# Simple question
gemini-termux ask "Explain quantum computing"

# With file input
gemini-termux ask "What's in this image?" --image photo.jpg

# Stream response
gemini-termux ask "Write a story" --stream

File Analysis

# Analyze image
gemini-termux chat --image screenshot.png

# Multiple files
gemini-termux chat --file document.pdf --file data.csv

# Supported: PNG, JPG, WEBP, PDF, TXT, CSV, JSON

Configuration

# View current config
gemini-termux config show

# Set model
gemini-termux config set model gemini-2.0-flash-exp

# Set temperature
gemini-termux config set temperature 0.7

# Reset to defaults
gemini-termux config reset

⚙️ Configuration

Config File Location

~/.config/gemini-cli/config.toml

Example Configuration

[api]
model = "gemini-2.0-flash-exp"
timeout = 60

[generation]
temperature = 0.9
top_p = 0.95
top_k = 40
max_output_tokens = 8192

[ui]
theme = "monokai"
syntax_highlighting = true
show_timestamps = true
streaming = true

[history]
enabled = true
max_entries = 1000
auto_save = true

[clipboard]
use_termux_api = true

Available Models

  • gemini-2.0-flash-exp - Fast, multimodal (Recommended)
  • gemini-2.0-flash-thinking-exp - Advanced reasoning
  • gemini-1.5-pro - Most capable
  • gemini-1.5-flash - Fast & efficient
  • gemini-1.5-flash-8b - Lightweight

🔧 Advanced Usage

Environment Variables

# API Configuration
export GEMINI_API_KEY="your-key"
export GEMINI_MODEL="gemini-2.0-flash-exp"

# Behavior
export GEMINI_STREAMING=true
export GEMINI_DEBUG=false

Batch Processing

# Process multiple questions
cat questions.txt | while read question; do
    gemini-termux ask "$question" >> answers.txt
done

# Analyze all images
for img in *.png; do
    gemini-termux ask "Describe this" --image "$img"
done

🛠️ Troubleshooting

Common Issues

"API key not found"

export GEMINI_API_KEY="your-key-here"
echo 'export GEMINI_API_KEY="your-key"' >> ~/.bashrc

"Clipboard not working"

pkg install termux-api

"Module not found"

pip install --break-system-packages -r requirements.txt --force-reinstall

Debug Mode

gemini-termux --debug chat
gemini-termux doctor  # Check installation

🤝 Contributing

Contributions welcome!

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing)
  3. Commit changes (git commit -m 'Add feature')
  4. Push to branch (git push origin feature/amazing)
  5. Open Pull Request

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

  • Google Gemini Team - For creating the original Gemini CLI and the amazing Gemini API
  • Official Gemini CLI - Inspiration for features and design
  • Termux community - For making Android development possible
  • All contributors to this project

Differences from Official CLI

This is a complete rewrite designed specifically for Termux:

Feature Official CLI This Project
Platform Node.js Python
Native Deps Yes (node-pty, keytar) None (pure Python)
Installation npm (requires compilation) pip (instant)
Authentication OAuth2 + Keychain API Key + File
Clipboard clipboardy (broken) Termux-API (native)
Termux Support ❌ Broken ✅ Native
File Size ~200MB+ ~50MB

📞 Support

Made with ❤️ for the Termux community

⬆ Back to Top