🤖 Gemini CLI – Termux Edition

Android/Termux optimized fork of Google Gemini CLI. Installs cleanly on Termux by skipping native modules and adding clipboard detection for Termux.

What This Is

Optimized Termux edition of google-gemini/gemini-cli.

This project focuses on maintaining a first-class experience for Gemini on Android/Termux. It provides critical adaptations for the mobile environment while tracking upstream development closely.

• Termux-First: Pre-configured for Android filesystem and clipboard.
• Lightweight: Native dependencies managed for ARM64 without complex compilation.
• Up-to-Date: Synchronized with the latest Google Gemini CLI features.

Why This Fork?

The official @google/gemini-cli fails to install on Termux due to native module compilation issues:

gyp: Undefined variable android_ndk_path in binding.gyp

Known Issues (Official Version):

• #7895 - Install fail on Termux Android
• #11254 - Build fails on Node v24 + arm64
• #8254 - Failed to update on Android/Termux

This fork solves these issues by:

1. Removing node-pty from dependencies (uses child_process fallback)
2. Skipping native module compilation that requires Android NDK
3. Adding Termux-specific environment detection and clipboard support

Installation (Termux)

Option 1: From npm (Recommended)

pkg update && pkg upgrade -y
pkg install nodejs-lts -y
npm install -g @mmmbuto/gemini-cli-termux

gemini --version  # expected: 0.22.2-termux (npm latest); 0.22.7-termux available on testing channel

Option 2: Build from source (GitHub)

Note: Direct npm install -g github:... is not supported due to build requirements. Use npm installation above, or build from source:

pkg update && pkg upgrade -y
pkg install nodejs-lts git -y
git clone https://github.com/DioNanos/gemini-cli-termux.git
cd gemini-cli-termux
npm install --ignore-optional --ignore-scripts
npm run bundle
npm link  # or: node bundle/gemini.js

gemini --version

Authentication on Termux

Termux doesn't support popup windows for Google login. Use debug mode to get the auth URL:

gemini --debug
# Then type: /auth
# Copy the displayed URL to your browser
# Complete authentication and return to Termux

Or install termux-api for automatic browser opening:

pkg install termux-api
gemini  # Browser will open automatically

Termux Optimizations

• Smart Clipboard: Auto-detects Android environment to enable seamless clipboard operations (fixes TERMUX__PREFIX).
• Streamlined Install: Native PTY/keychain deps are omitted on Termux (fallback to child_process + file-based tokens), avoiding native builds.
• Clean UX: Suppresses desktop-centric warnings (like home directory checks) to optimize the experience for mobile terminal usage.
• ARM64 Native: Bundled specifically for Android architecture.

Environment Specifics

• Shell Integration: Uses robust child_process fallback instead of node-pty for maximum stability on Android.
• Credentials: Keys are stored in standard config files for portability (no dependency on system keychains).
• Parser: Simplified Bash parsing to reduce heavy binary dependencies.

Documentation & Fixes

📚 Complete Documentation

• Test Results
  • GEMINI_TEST_REPORT_v0.22.7.md — testing channel
  • GEMINI_TEST_REPORT_v0.22.2.md — stable baseline
• Test Suite - Test methodology and checklist
• Patches & Fixes - Known issues and workarounds

🔧 Common Issues & Solutions

| Issue | Quick Fix | Documentation | | --------------------- | ----------------------------- | --------------------------------------------------- | | node-pty warning | export NODE_NO_WARNINGS=1 | Details | | CLI syntax (--json) | Use -o json instead | Details | | Hooks commands | Use interactive mode /hooks | Details |

📝 Quick Reference

# Correct usage examples
gemini -o json "your prompt"              # ✅ JSON output
gemini --output-format json "prompt"      # ✅ Also works
gemini --json "prompt"                    # ❌ Wrong syntax

# Quiet mode (suppress warnings)
export NODE_NO_WARNINGS=1
gemini "your prompt"

# Hooks management (interactive only)
gemini           # Start interactive mode
/hooks           # Manage hooks

See docs/patches/README.md for complete solutions.

Updating

npm install -g @mmmbuto/gemini-cli-termux@latest

Versions

• latest / stable: 0.22.2-termux (default npm dist-tag)
• testing: 0.22.7-termux (adds Gemini 3 Flash preview; install explicitly)
• previous: 0.21.4-termux

Tests

• Suite: GEMINI_TEST_SUITE.md
• Latest reports:
  • GEMINI_TEST_REPORT_v0.22.7.md — testing channel, PASS (static verification) on Termux: version/env, CLI basics, non-interactive JSON, Termux-API, context memory, Gemini 3 Flash, agent TOML loader, patches integrity. Agent shell security filter blocks complex run_shell_command calls in this environment (known restriction); CLI itself verified via --version.
  • GEMINI_TEST_REPORT_v0.22.2.md — stable baseline, PASS with expected optional-native warnings.

Termux-API Integration

This fork supports optional integration with Termux-API commands for Android device access. Enable Gemini to interact with your device hardware and Android features.

Context memory + TTS note:

• The Termux fork ships JSON context memory at ~/.gemini/context_memory/{base.json,user.json,user.journal.jsonl}. In /settings → Context Memory you can toggle autoload, choose the primary source, and (if needed) enable writes to base.json via Allow Base Memory Writes.
• TTS notifications are controlled by /settings → Notifications → Enable TTS Notifications. When disabled, termux-tts-speak is blocked even if an agent asks for it. These behaviors are merge-safe and confined to Termux patches.

Quick Setup

# Install Termux-API package
pkg install termux-api jq

# Copy tool discovery scripts
mkdir -p ~/.config/gemini/termux-tools
cp scripts/termux-tools/*.sh ~/.config/gemini/termux-tools/

# Configure in settings
cat > ~/.config/gemini/settings.json << 'EOF'
{
  "tool_discovery_command": "bash ~/.config/gemini/termux-tools/discovery.sh",
  "tool_call_command": "bash ~/.config/gemini/termux-tools/call.sh"
}
EOF

# Test
gemini "What's my battery status?"

Supported Commands

Battery, Clipboard, Toast, Notifications, TTS, Vibrate, Torch, WiFi info, Location, Camera, Dialog, Share, and more.

See docs/termux-api/ for complete documentation.

v0.22.7-termux (testing) Highlights

• Gemini 3 Flash preview enabled (gemini-3-flash-preview) with help/docs visibility.

• Context Memory (default ON): strict, merge-safe JSON memory at ~/.gemini/context_memory/{base.json,user.json,user.journal.jsonl} with per-source autoload, primary selector, and GEMINI.md bootstrap on first run.

• Deterministic compaction: journal append-only with incremental offsets, closed JSON schemas, key-based upsert, TTL/ephemeral guardrails, sensitivity=high excluded from autoload.

• Base write toggle: enable/disable writes to base.json from /save_memory target=base (off by default, merge-safe).

• TTS toggle: new /settings switch to allow/block termux-tts-speak; shell tool blocks TTS when disabled.

• Termux-first shell: non-interactive commands (echo, pwd, ls) work without native PTY deps; optional natives removed for faster installs.

• Termux-API tools: discovery/call scripts under scripts/termux-tools/ expose Termux APIs as tools (battery, tts, camera, etc.).

See docs/cli/context-memory.md for the detailed memory layout and settings.

v0.22.2-termux Improvements

This release includes significant improvements to the Termux experience:

Installation

• Clear postinstall message - No more confusion about native module warnings
• make termux-install - One-command build from source
• termux-setup.sh - Helper script for first-time setup

Developer Experience

• Termux detection utility - isTermux() and detectTermuxEnvironment()
• Punycode warning suppression - Cleaner output on Android
• Merge-safe patches - Easy to maintain after upstream sync
• check-termux-patches.sh - Verify patches after merge

Documentation

• Complete Termux-API integration plan
• 60+ commands documented with parameters
• Merge strategy guide for maintainers

Changelog (Termux)

• 0.22.1-termux: Termux-API integration, improved installation UX, Termux detection utility, merge automation scripts.
• 0.22.0-termux: Sync with upstream (0.21.0-nightly); added hide banner patch; restored ARM64 dependency.
• 0.21.4-termux: (Previous)

Upstream Tracking

• Upstream: https://github.com/google-gemini/gemini-cli
• Divergent files: esbuild.config.js, docs/TERMUX.md, package.json, README.md, test-gemini/*

License

Apache 2.0 (same as upstream). See LICENSE.