TermuxAI

---

📋 Overview

TermuxAI is a production-ready React Native Android application that combines AI Agent capabilities with Termux through MCP (Model Context Protocol) server integration. It enables autonomous command execution, file management, system monitoring, and intelligent conversation with OpenRouter-powered language models.

🎯 Key Highlights

• 🤖 AI Agent via OpenRouter: Powered by hundreds of models via OpenRouter (GPT, Claude, Gemini, Llama)
• 🔌 MCP Protocol: Seamless communication with Termux environment
• 💬 Real-time Streaming: Live AI response streaming
• 📁 File Manager: Browse, edit, and manage Termux files
• 🖥️ System Monitor: Real-time system information and command history
• ⚙️ Configurable: Extensive settings for customization
• 🔒 Secure: Token-based authentication and sandboxed execution

---

✨ Features

🤖 AI Agent Chat

• Real-time conversation with AI using the OpenRouter API
• Streaming responses for immediate feedback
• Command suggestion and auto-execution (optional)
• Multi-model support (Llama 3.1 8B/70B/405B, Nemotron 4, Mixtral)
• Conversation history with message types (user/assistant/system)
• Smart command detection in AI responses

📂 File Manager

• Browse Termux file system (/data/data/com.termux/files/home)
• Read and edit files directly
• Create new files with content
• Delete files and directories
• Visual file type indicators
• File size and permissions display

🖥️ System Monitor

• Real-time system information (CPU, Memory, Storage, Battery)
• Command execution with output display
• Command history tracking with exit codes
• Network status monitoring
• System uptime and resource usage

⚙️ Settings & Configuration

• OpenRouter API: Secure API key storage
• Model Selection: Choose from 5+ AI models
• MCP Server: Configure server URL and auth token
• AI Parameters: Adjust temperature (0.0-1.0) and max tokens (512-4096)
• Behavior: Toggle streaming, auto-execute, dark mode
• Security: Password-protected fields with show/hide toggle

---

🚀 Installation

Prerequisites

• Android Device/Emulator: Android 8.0+ (API level 26+)
• Node.js: v18+ and npm
• React Native CLI: Latest version
• Android Studio: For Android SDK and build tools
• Termux: Installed on Android device with MCP server running

Quick Start

1. Clone the repository

   git clone https://github.com/yourusername/TermuxAI.git
   cd TermuxAI
   

2. Install dependencies

   npm install
   

3. Setup Android environment

   # Ensure ANDROID_HOME is set
   export ANDROID_HOME=$HOME/Android/Sdk
   export PATH=$PATH:$ANDROID_HOME/emulator
   export PATH=$PATH:$ANDROID_HOME/tools
   export PATH=$PATH:$ANDROID_HOME/tools/bin
   export PATH=$PATH:$ANDROID_HOME/platform-tools
   

4. Start Metro bundler

   npm start
   

5. Build and run on Android

   # Development build
   npm run android
   
   # Production build
   cd android && ./gradlew assembleRelease
   

📦 Pre-built APK

Download the latest release APK from Releases page.

---

⚙️ Configuration

1. OpenRouter API Setup

1. Visit https://openrouter.ai/ and create an account
2. Create an account and generate an API key
3. Open TermuxAI → Settings → OpenRouter API Key
4. Paste your API key and save
5. Select your preferred model

2. Termux MCP Server Setup

On your Android device (Termux):

# Install Node.js
pkg update && pkg upgrade
pkg install nodejs

# Clone and setup MCP server (use the one from our previous build)
cd ~
wget https://www.genspark.ai/api/files/s/Z8LvHmeD -O termux-mcp-server.tar.gz
tar -xzf termux-mcp-server.tar.gz
cd termux-mcp-server

# Install dependencies
npm install

# Start the server
npm start

# Server will run on http://127.0.0.1:8080

In TermuxAI app:

1. Open Settings → MCP Server Configuration
2. Enter server URL: http://127.0.0.1:8080
3. (Optional) Set auth token if configured on server
4. Save configuration

3. Environment Variables (Development)

Create .env file in project root:

OpenRouter_API_KEY=your_openrouter_api_key_here
MCP_SERVER_URL=http://127.0.0.1:8080
MCP_AUTH_TOKEN=your_optional_token

---

📱 Usage

Chat with AI Agent

1. Open Chat tab
2. Type your message or question
3. AI will respond with suggestions or answers
4. If AI suggests a command, you can:
   • Review the command
   • Execute it with one tap
   • View the output in real-time

Example Conversations:

User: List all files in my home directory
AI: I'll execute: ls -la ~
[Output displayed in system message]

User: What's my CPU usage?
AI: Let me check your system resources...
[Shows parsed system information]

User: Create a Python script to calculate fibonacci
AI: [Generates script and offers to save it]

File Management

1. Open Files tab
2. Navigate through directories
3. Tap folder to open, file to view/edit/delete
4. Use + button to create new files
5. Edit and save directly in the app

System Monitoring

1. Open System tab
2. View real-time system metrics
3. Execute commands in the terminal section
4. Review command history
5. Refresh to update information

Settings Customization

1. Open Settings tab
2. Configure:
   • OpenRouter API: Set API key and model
   • MCP Server: Server URL and auth
   • AI Behavior: Streaming, auto-execute, temperature, max tokens
3. Save changes (persisted across app restarts)

---

🛠️ Development

Project Structure

TermuxAI/
├── android/                 # Android native code
├── ios/                     # iOS native code (future)
├── src/
│   ├── screens/            # React Native screens
│   │   ├── ChatScreen.tsx
│   │   ├── FileManagerScreen.tsx
│   │   ├── SystemScreen.tsx
│   │   └── SettingsScreen.tsx
│   ├── services/           # Core services
│   │   ├── AIAgent.ts      # OpenRouter API client
│   │   └── MCPClient.ts    # MCP protocol client
│   ├── store/              # Redux state management
│   │   ├── index.ts
│   │   └── slices/
│   │       ├── chatSlice.ts
│   │       ├── settingsSlice.ts
│   │       └── systemSlice.ts
│   └── types/              # TypeScript type definitions
├── .github/                # GitHub Actions workflows
├── App.tsx                 # Root component
├── package.json
├── tsconfig.json
└── README.md

Tech Stack

• Framework: React Native 0.74
• Language: TypeScript 5.3
• State Management: Redux Toolkit
• Navigation: React Navigation
• HTTP Client: Axios
• Storage: AsyncStorage
• Icons: React Native Vector Icons
• AI API: OpenRouter (OpenAI SDK compatible)

Building from Source

# Install dependencies
npm install

# Run TypeScript check
npx tsc --noEmit

# Run linter
npx eslint . --ext .ts,.tsx --fix

# Run tests
npm test

# Build Android APK
cd android
./gradlew assembleRelease

# Output: android/app/build/outputs/apk/release/app-release.apk

Debugging

# Enable React Native debugger
npm start -- --reset-cache

# Android logs
adb logcat | grep ReactNative

# Redux DevTools (in development)
# Install Redux DevTools browser extension

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Code Standards

• Follow TypeScript best practices
• Use ESLint and Prettier for code formatting
• Write meaningful commit messages
• Add tests for new features
• Update documentation

---

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See LICENSE file for details.

---

🙏 Acknowledgments

• OpenRouter: For AI inference across hundreds of models
• Termux: For Android Linux environment
• MCP Protocol: For standardized agent communication
• React Native: For cross-platform mobile development
• TermuxGPT: Inspiration for MCP integration

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

---

🗺️ Roadmap

• iOS support
• Voice input/output
• Plugin system for custom commands
• Cloud sync for conversations
• Multi-language support
• Advanced file editing (syntax highlighting)
• Docker integration
• SSH remote server support
• Workflow automation builder

---