@mmmbuto/gemini-cli-termux 0.22.6-termux → 0.24.0-termux

package/README.md

@@ -29,7 +29,7 @@ pkg update && pkg upgrade -y
 pkg install nodejs-lts -y
 npm install -g @mmmbuto/gemini-cli-termux
 
-gemini --version  # expected: 0.22.3-termux (latest)
+gemini --version  # expected: 0.24.0-termux (npm latest)
 ```
 
 Build from source:
@@ -64,9 +64,12 @@ node bundle/gemini.js --version
 
 ### 📚 Complete Documentation
 
-- **[Test Results](./GEMINI_TEST_REPORT_v0.22.1.md)** - Comprehensive test
-  report with analysis
+- **Test Results**
+  - [GEMINI_TEST_REPORT_v0.24.0.md](./GEMINI_TEST_REPORT_v0.24.0.md) — PASS
+    (partial execution; interactive steps pending)
 - **[Test Suite](./GEMINI_TEST_SUITE.md)** - Test methodology and checklist
+- **[Context Memory](./docs/cli/context-memory.md)** - Memory modes, JIT + JSON,
+  and setup guide
 - **[Patches & Fixes](./docs/patches/)** - Known issues and workarounds
 
 ### 🔧 Common Issues & Solutions
@@ -102,37 +105,34 @@ See [docs/patches/README.md](./docs/patches/README.md) for complete solutions.
 npm install -g @mmmbuto/gemini-cli-termux@latest
 ```
 
-### Versions
+### Changelog (0.24.0-termux)
 
-- **latest**: 0.22.3-termux (this build)
-- **stable**: 0.22.3-termux
+- **Memory Mode presets** in `/settings → Memory` (default / jit / jit+json).
+- **JIT + JSON** combined memory support (ContextManager now loads JSON memory).
+- **Memory settings reorganized** into a dedicated section; MCP import
+  categories hidden from UI.
+- **Docs & tests refreshed** for 0.24.0-termux.
 
 ## Tests
 
 - Suite: [`GEMINI_TEST_SUITE.md`](./GEMINI_TEST_SUITE.md)
 - Latest report:
-  [`GEMINI_TEST_REPORT_v0.22.1.md`](./GEMINI_TEST_REPORT_v0.22.1.md)
-  - PASS with warnings (node-pty optional missing log; `--version --json`
-    outputs plain string; config-path flag unsupported; extensions settings
-    needs subcommand).
-  - Non-interactive/file tests executed via agent; Termux checks pass;
-    package/bundle verified.
-  - Optional native modules (node-pty, keytar, tree-sitter-bash) not built on
-    Termux → warnings expected; CLI remains functional.
+  - [`GEMINI_TEST_REPORT_v0.24.0.md`](./GEMINI_TEST_REPORT_v0.24.0.md) — PASS
+    (partial execution; interactive steps pending). Notes include
+    non‑interactive tool confirmation limits.
 
-## Termux-API Integration (NEW!)
+## 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:**
+## 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`.
+  `/settings → Memory` you can select **Memory Mode** (default / jit / jit+json)
+  and adjust Context Memory options (autoload, primary ordering, base 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
@@ -169,7 +169,10 @@ See [docs/termux-api/](./docs/termux-api/) for complete documentation.
 
 ---
 
-## v0.22.3-termux Highlights
+## 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
@@ -188,7 +191,7 @@ See [docs/termux-api/](./docs/termux-api/) for complete documentation.
 
 See `docs/cli/context-memory.md` for the detailed memory layout and settings.
 
-## v0.22.1-termux Improvements
+## v0.22.2-termux Improvements
 
 This release includes significant improvements to the Termux experience:
 

package/bundle/README.md

@@ -0,0 +1,239 @@
+# 🤖 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.
+
+[![npm](https://img.shields.io/npm/v/@mmmbuto/gemini-cli-termux?style=flat-square&logo=npm)](https://www.npmjs.com/package/@mmmbuto/gemini-cli-termux)
+[![downloads](https://img.shields.io/npm/dt/@mmmbuto/gemini-cli-termux?style=flat-square)](https://www.npmjs.com/package/@mmmbuto/gemini-cli-termux)
+[![ko-fi](https://img.shields.io/badge/☕_Support-Ko--fi-FF5E5B?style=flat-square&logo=ko-fi)](https://ko-fi.com/dionanos)
+
+---
+
+## 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.
+
+## Installation (Termux)
+
+```bash
+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
+```
+
+Build from source:
+
+```bash
+git clone https://github.com/DioNanos/gemini-cli-termux.git
+cd gemini-cli-termux
+npm install --ignore-optional --ignore-scripts
+npm run build && npm run bundle
+node bundle/gemini.js --version
+```
+
+## 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](./GEMINI_TEST_REPORT_v0.22.7.md) — testing
+    channel
+  - [GEMINI_TEST_REPORT_v0.22.2.md](./GEMINI_TEST_REPORT_v0.22.2.md) — stable
+    baseline
+- **[Test Suite](./GEMINI_TEST_SUITE.md)** - Test methodology and checklist
+- **[Patches & Fixes](./docs/patches/)** - Known issues and workarounds
+
+### 🔧 Common Issues & Solutions
+
+| Issue                 | Quick Fix                     | Documentation                                       |
+| --------------------- | ----------------------------- | --------------------------------------------------- |
+| node-pty warning      | `export NODE_NO_WARNINGS=1`   | [Details](./docs/patches/node-pty-warning.md)       |
+| CLI syntax (`--json`) | Use `-o json` instead         | [Details](./docs/patches/cli-syntax-differences.md) |
+| Hooks commands        | Use interactive mode `/hooks` | [Details](./docs/patches/hooks-interactive-only.md) |
+
+### 📝 Quick Reference
+
+```bash
+# 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](./docs/patches/README.md) for complete solutions.
+
+## Updating
+
+```bash
+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`](./GEMINI_TEST_SUITE.md)
+- Latest reports:
+  - [`GEMINI_TEST_REPORT_v0.22.7.md`](./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`](./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
+
+```bash
+# 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/](./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.

package/bundle/docs/TERMUX.md

@@ -0,0 +1,97 @@
+# Gemini CLI – Termux Guide
+
+How to install and run the Termux edition `@mmmbuto/gemini-cli-termux` on
+Android.
+
+## Prerequisites
+
+- Termux installed
+- Node.js 20+ (`pkg install nodejs-lts -y`)
+- Git (only if building from source)
+
+## Install via npm (recommended)
+
+```bash
+npm install -g @mmmbuto/gemini-cli-termux
+
+gemini --version
+# expected: 0.22.0-termux (latest)
+```
+
+Features of the npm build
+
+- ARM64/Android bundle included
+- Termux clipboard patch (`PREFIX` -> `TERMUX__PREFIX`)
+- Native modules left optional; no NDK required
+
+## Build from source (Termux fork)
+
+```bash
+git clone https://github.com/DioNanos/gemini-cli-termux.git
+cd gemini-cli-termux
+npm install --ignore-optional --ignore-scripts
+npm run build && npm run bundle
+node bundle/gemini.js --version
+```
+
+## Known issues
+
+1. Native modules (keytar, node-pty, tree-sitter-bash) fail on Termux → ignored
+   with the install flags above.
+2. Clipboardy TERMUX\_\_PREFIX is patched in the bundle.
+3. Node punycode warning is harmless; optional:
+   `node --no-deprecation bundle/gemini.js`.
+
+## Limitations
+
+- No full PTY support → some interactive shell features limited
+- No secure keychain → credentials stored in plain config files
+- Bash parsing simplified (no tree-sitter)
+
+## Update
+
+- npm: `npm install -g @mmmbuto/gemini-cli-termux@latest`
+- source:
+  `git pull && npm install --ignore-optional --ignore-scripts && npm run build && npm run bundle`
+
+## Termux-API Support (Optional)
+
+Enable access to Android hardware and APIs:
+
+1. Install Termux-API package:
+
+   ```bash
+   pkg install termux-api jq
+   ```
+
+2. Install Termux:API app from F-Droid
+
+3. Setup tool discovery:
+
+   ```bash
+   # Copy scripts to config
+   mkdir -p ~/.config/gemini/termux-tools
+   cp scripts/termux-tools/*.sh ~/.config/gemini/termux-tools/
+   chmod +x ~/.config/gemini/termux-tools/*.sh
+
+   # Configure in settings.json
+   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
+   ```
+
+4. Test:
+   ```bash
+   gemini "What's my battery status?"
+   ```
+
+See [docs/termux-api/](./docs/termux-api/) for complete documentation.
+
+## Report Termux issues
+
+Use the fork issues: https://github.com/DioNanos/gemini-cli-termux/issues
+
+Sunset: will deprecate when upstream adds native Termux support.

package/bundle/docs/architecture.md

@@ -0,0 +1,80 @@
+# Gemini CLI Architecture Overview
+
+This document provides a high-level overview of the Gemini CLI's architecture.
+
+## Core components
+
+The Gemini CLI is primarily composed of two main packages, along with a suite of
+tools that can be used by the system in the course of handling command-line
+input:
+
+1.  **CLI package (`packages/cli`):**
+    - **Purpose:** This contains the user-facing portion of the Gemini CLI, such
+      as handling the initial user input, presenting the final output, and
+      managing the overall user experience.
+    - **Key functions contained in the package:**
+      - [Input processing](/docs/cli/commands.md)
+      - History management
+      - Display rendering
+      - [Theme and UI customization](/docs/cli/themes.md)
+      - [CLI configuration settings](/docs/get-started/configuration.md)
+
+2.  **Core package (`packages/core`):**
+    - **Purpose:** This acts as the backend for the Gemini CLI. It receives
+      requests sent from `packages/cli`, orchestrates interactions with the
+      Gemini API, and manages the execution of available tools.
+    - **Key functions contained in the package:**
+      - API client for communicating with the Google Gemini API
+      - Prompt construction and management
+      - Tool registration and execution logic
+      - State management for conversations or sessions
+      - Server-side configuration
+
+3.  **Tools (`packages/core/src/tools/`):**
+    - **Purpose:** These are individual modules that extend the capabilities of
+      the Gemini model, allowing it to interact with the local environment
+      (e.g., file system, shell commands, web fetching).
+    - **Interaction:** `packages/core` invokes these tools based on requests
+      from the Gemini model.
+
+## Interaction flow
+
+A typical interaction with the Gemini CLI follows this flow:
+
+1.  **User input:** The user types a prompt or command into the terminal, which
+    is managed by `packages/cli`.
+2.  **Request to core:** `packages/cli` sends the user's input to
+    `packages/core`.
+3.  **Request processed:** The core package:
+    - Constructs an appropriate prompt for the Gemini API, possibly including
+      conversation history and available tool definitions.
+    - Sends the prompt to the Gemini API.
+4.  **Gemini API response:** The Gemini API processes the prompt and returns a
+    response. This response might be a direct answer or a request to use one of
+    the available tools.
+5.  **Tool execution (if applicable):**
+    - When the Gemini API requests a tool, the core package prepares to execute
+      it.
+    - If the requested tool can modify the file system or execute shell
+      commands, the user is first given details of the tool and its arguments,
+      and the user must approve the execution.
+    - Read-only operations, such as reading files, might not require explicit
+      user confirmation to proceed.
+    - Once confirmed, or if confirmation is not required, the core package
+      executes the relevant action within the relevant tool, and the result is
+      sent back to the Gemini API by the core package.
+    - The Gemini API processes the tool result and generates a final response.
+6.  **Response to CLI:** The core package sends the final response back to the
+    CLI package.
+7.  **Display to user:** The CLI package formats and displays the response to
+    the user in the terminal.
+
+## Key design principles
+
+- **Modularity:** Separating the CLI (frontend) from the Core (backend) allows
+  for independent development and potential future extensions (e.g., different
+  frontends for the same backend).
+- **Extensibility:** The tool system is designed to be extensible, allowing new
+  capabilities to be added.
+- **User experience:** The CLI focuses on providing a rich and interactive
+  terminal experience.