CodeDroid — Mobile Code Execution Engine for Android & iOS

Free, open-source mobile IDE and code execution engine — write, compile, run, and debug Python, Rust, Go, C++, and 10 languages directly on your Android or iOS device. No laptop needed, running with bare-metal performance.

---

📖 Table of Contents

1. What is CodeDroid?
2. Application Preview
3. Key Capabilities & Features
4. Ecosystem & Architectural Blueprints
5. Native Wrapper Applications (Tauri & Flutter)
6. Supported Languages & Setup Directory
7. Smart Code Suggestions & AI Rule Engine
8. Termux Android Installation Details
9. Cross-Device & iOS Network Connectivity
10. LSP Binary Executable Path Resolution
11. Upcoming Features & Roadmap
12. Contributing
13. License

---

CodeDroid is a high-performance mobile programming environment that compiles and runs your code directly on-device with zero virtualization. It is built as three integrated modules:

1. codedroid_api (Backend Engine): A lightweight, multi-threaded server written in Rust (Axum). It directly invokes system compilers (rustc, gcc, kotlinc, etc.), manages asynchronous execution streams, coordinates multiple concurrent Language Server Protocol (LSP) instances, and handles local dependency installation.
2. codedroid_frontend (Web IDE): A reactive, mobile-first IDE built using the Leptos web framework and compiled to WebAssembly (WASM). It runs entirely inside any web browser (Safari, Chrome, Firefox) and utilizes high-performance code-rendering pipelines to provide syntax highlighting, bracket matching, file drawers, autocomplete drop-downs, and compiler error overlays.
3. apps (Native Wrappers): Cross-platform native wrappers bundling the WebAssembly frontend. Includes Tauri for desktop platforms (macOS, Windows, Linux) and Flutter for mobile platforms (Android) running a lightweight, local web server background task to bypass browser WebAssembly restrictions.

Unlike typical cloud-based sandboxes or emulated JS runtimes, CodeDroid exposes the real filesystem and real binaries of your host device (like a Termux Android shell or local macOS/Linux installation).

---

📱 Application Preview

Create a New Project	Add Dependencies

Auto Completion & Suggestions	Error Diagnostics	Hover Documentation

In-File Search	Global Project Search

---

✨ Key Capabilities & Features

• Mobile-First Touch Architecture: Designed specifically for small touchscreens (320px–768px). Features a slide-out file explorer overlay drawer, auto-collapsing sidebar upon opening files, persistent touch targets for closing tabs, and custom layout controls utilizing CSS 100dvh to prevent keyboard resize clipping.

• Universal Drag-to-Resize Layout: Dynamically adjust sidebars, bottom terminal consoles, and active editor split panes using intuitive touch-and-drag handle borders. Panel dimensions are persistently saved to LocalStorage for continuity across sessions.

• Interactive Web Terminal: Run shell commands directly using a fully connected terminal console (backed by real system PTY shells) with raw stream capturing, exit code detection, and custom termination controls.

• Integrated Git Console: Stage or unstage workspace changes, view line-by-line colored diff overlays directly inside the editor, generate commit messages with AI suggestions, clone repositories, and push/pull updates directly from the IDE sidebar. See the GitHub Setup Guide for credentials configuration.

• Live Reload Development Server: Spin up a local static server inside any project directory that monitors folder modifications and dynamically injects hot-reloading scripts, bypassing manual browser refresh cycles.

• Rich Media & Document Viewers: Native tab views to render images, video playback, and audio files directly, alongside a side-by-side Markdown layout editor and previewer.

• LSP-powered IntelliSense: Floating completion panels, in-line diagnostics, hover tooltips, definition lookups, and references. Automatically hides bloated metadata subpanels on narrow screens to prevent viewport clipping.

• Save-Triggered Synchronization: Supports immediate file-writing to the host disk on save, triggering automatic LSP change notifications (textDocument/didChange & textDocument/didSave) which instantly update error diagnostics.

• Advanced File Manager: Create, copy, paste, delete, move, or rename files and directories. Full recursive operations synchronized instantly to local disk and LocalStorage states.

• Persistent Editor State: Restores open file tabs, split views, active cursor position, and panel visibility structures when reloading.

• Offline Fallback Mode: Works entirely offline with local-first file caching. If the LSP is unavailable, CodeDroid falls back to an internal regex token parser to provide syntax-matching autocomplete suggestions.

---

🏗️ Ecosystem & Architectural Blueprints

Codebase Directory Structures & Module Overview

The full repository tree (backend, client-side frontend, native wrapper apps, and scripts) is documented in PROJECT_STRUCTURE.md.

Flow Diagram: Document Sync & Compilation Lifecycle

flowchart TD
A["Web IDE (Client)"]
B["Axum Backend (Server)"]
C["LSP Client (Stdio/RPC)"]
D["Local File System (/sdcard/...)"]
A -- "1. Save (Ctrl+S)" --> B
A -- "2. notify_file_changed()" --> C
B -- "3. Sync to disk" --> D
C -- "JSON-RPC" --> D
B -- "4. Return JSON diagnostics" --> A

Loading

Flow Diagram: Diagnostic Polling Loops

sequenceDiagram
autonumber
actor Client as Client (Web IDE)
participant Backend as Axum Backend
participant LSP as Target LSP
Client->>Backend: POST /diagnostics (Wait for version update)
Backend->>LSP: didChange / didSave
LSP-->>Backend: publishDiagnostics (Async stderr stream)
Backend-->>Client: Return Diagnostics (JSON range & severity)

Loading

---

📱 Native Wrapper Applications (Tauri & Flutter)

CodeDroid offers native client wrappers that bundle the codedroid_frontend WebAssembly package directly into target app environments.

🔄 Asset Synchronization Flow

Whenever the Leptos frontend code is modified, it must be compiled and synchronized to both the Flutter and Tauri directories. An automated build script is provided:

# Run from repository root
./apps/sync_assets.sh

This script builds codedroid_frontend in release mode and mirrors the static outputs to both application directories automatically.

⚙️ Cross-Compiling Rust API for Android/Linux

The Android Flutter application bundles pre-compiled static Musl ELF binaries of codedroid_api (aarch64 and x86_64) to run the backend server inside the local environment (PRoot/Alpine).

To cross-compile and deploy the latest backend binary updates from a macOS/Linux machine to the Flutter assets:

1. Ensure you have the musl-cross toolchain (specifically aarch64-linux-musl-gcc and x86_64-linux-musl-gcc) installed on your host system.
2. Run the automated compilation, stripping, and deployment script from the repository root:

   ./build_android_binaries.sh

3. Rebuild the Flutter Android application:

   cd apps/flutter_android
   flutter build apk --split-per-abi

📱 Flutter (Android) Wrapper

Located in apps/flutter_android/. It launches a background InAppLocalhostServer on port 8080 to serve the static assets offline.

• Why Localhost? Modern mobile WebViews block WebAssembly streaming compile calls if executed over the file:// protocol. The local server enables WebAssembly and provides cookies/LocalStorage persistence.
• Theme & Style: Tailored with a custom Material 3 Dark theme matching the web IDE, featuring matching system bar colors and transparent status integrations.
• For run and build instructions, see the Flutter Android README.

💻 Tauri (Desktop) Wrapper

Located in apps/tauri_desktop/. It uses Tauri to pack the WebAssembly interface into native desktop clients.

• Ultra-lightweight: Compiles to under 20MB, utilizing the native system web engines (Webkit2GTK / WebView2) to reduce RAM usage.
• Cross-Platform: Supports native macOS, Windows, and Linux window environments.
• For run and build instructions, see the Tauri Desktop README.

---

📊 Supported Languages & Setup Directory

This guide details exactly how to configure compilers, runtimes, and auto-suggestion language servers (LSP) for each language. All shell operations are to be run in your Termux or system shell.

---

🦀 Rust

Get a full, desktop-grade Rust development environment on your phone.

• Compiler & Tools: Install rust and cargo:

  pkg install rust

• Language Server (LSP): Install rust-analyzer for real-time completions, diagnostics, and hover hints:

  pkg install rust-analyzer

• Enable Completions: Start the API server, open any .rs file in the IDE, and start typing. CodeDroid automatically hooks into rust-analyzer.

---

🐍 Python

Set up Python script execution and IntelliSense formatting.

• Python Runtime: Install Python and pip:

  pkg install python

• Language Server (LSP): Install python-lsp-server (pylsp) via pip:

  pip install python-lsp-server

• Usage: Create any .py file. CodeDroid automatically runs completions and highlights syntax.

---

🐹 Go

Full Go compilation toolchain and suggestions on-device.

• Go Compiler: Install the Go programming toolset:

  pkg install golang

• Language Server (LSP): Install gopls (Go Please) to enable completions:

  pkg install gopls

• Usage: Open any folder containing go.mod, edit .go files, and completions will populate.

---

🛡️ C & C++

High-performance native coding using LLVM tools.

• Compiler Toolchain: Install LLVM/Clang and make:

  pkg install clang build-essential

• Language Server (LSP): Install clangd for diagnostics and completions:

  pkg install clangd

• Usage: Create a .c or .cpp file. clangd acts as the back-end analyzer.

---

🎯 Dart

Build Dart CLI programs and scripts.

• Runtime & Toolset: Install Dart SDK:

  pkg install dart

• Language Server (LSP): Dart includes its language server inside the SDK. No separate installation required. CodeDroid resolves it automatically.

---

💎 Ruby

Execute scripts and resolve Gems.

• Ruby Runtime: Install ruby:

  pkg install ruby

• Language Server (LSP): Install the Solargraph gem:

  gem install solargraph

---

🍎 Swift

Develop Swift scripts inside Termux.

• Swift Runtime: Install Swift:

  pkg install swift

• Language Server (LSP): Swift includes the sourcekit-lsp binary. Ensure Xcode default toolchains are active if hosting on macOS.

---

🧬 Kotlin

Run compiled Kotlin bytecode.

• Compiler: Install Kotlin compiler packages:

  pkg install kotlin

• Language Server (LSP): Install kotlin-language-server from your system package manager.

---

🧪 Haskell, R, Perl, Pascal & Scala

Other supported scripting languages compile and run using their default packages:

• Haskell: Run pkg install ghc to compile .hs scripts.
• R: Run pkg install r-base to execute .R formulas.
• Perl: Run pkg install perl to execute .pl files.
• Pascal: Run pkg install fpc to compile .pas code with the Free Pascal Compiler.
• Scala: Run pkg install scala to run JVM-based Scala programs.

---

🧠 Smart Code Suggestions & AI Rule Engine

CodeDroid's suggestion engine in error_suggestions.rs parses compiler diagnostics and provides contextual explanations and code replacements.

Suggestions Rules Mapping

Rule Trigger	Matching Criteria	Code Replacements	Expected Result
Rust E0384 (Mutability)	cannot mutate immutable variable, cannot assign to immutable	Adds mut after the variable declaration let	Variable is marked mutable; compiler error resolves on save.
Rust Unused Variable	unused variable	Prepends an underscore _ to the identifier	Silences compiler warning flags.
Rust Type mismatch (String)	expected String, found &str	Appends .to_string() or .into()	Casts string literal to owned String struct.
Rust Borrow String	expected &str, found String	Prepends borrow operator & or appends .as_str()	Converts owned String reference to sliced slice.
Rust Integer mismatch	Mismatches of usize/u32/i32	Appends as usize or as _	Casts number types dynamically.
Rust Missing Imports	cannot find type/struct in scope for collections/sync	Inserts use std::collections::* or use std::sync::* at Line 0	Resolves undefined scope structures.
Rust Move Violations	cannot move out of shared reference	Appends .clone()	Creates owned duplicate data segment.
Python Indentation	IndentationError, unexpected indent	Informational alignment warning	Alerts layout tabs vs spaces anomalies.
Python Scope Resolution	NameError: name is not defined	Spell-checks declared symbols	Identifies typos or missing scope values.
JS / TS Scope Errors	cannot find name	Identifies missing export tags	Flags typos and missing package imports.

---

🛠️ Termux Android Installation Details

Termux serves as the native runtime engine on Android. For detailed steps, see TERMUX_SETUP.md.

1. F-Droid Repository: Do not download Termux from the Google Play Store (outdated packages and security warnings). Use F-Droid or direct APK download options.
2. Base Setup: Initialize Termux packages:

   pkg update && pkg upgrade -y

3. Core Dependencies:

   pkg install git rust clang build-essential nodejs-lts python go -y

4. Storage Integration: Connect storage paths to ensure files are visible inside download directories:

   termux-setup-storage

   This grants Termux filesystem read/write permissions to internal shared storage maps.

---

📡 Cross-Device & iOS Network Connectivity

CodeDroid allows you to use your iPad or iPhone as a code editor screen, while using an Android tablet or local PC running Termux/Rust as the compiler server.

 ┌──────────────────────────┐ ┌────────────────────────────────┐
│ iPhone / iPad / Browser │──WiFi──▶│ PC or Android (Termux Host) │
│ │ │ │
│ Open in Safari/Chrome: │ │ codedroid_api → port 3030 │
│ http://<HOST-IP>:8082 │ │ trunk serve → port 8082 │
└──────────────────────────┘ └────────────────────────────────┘

For detailed configurations, see NETWORK_ACCESS.md.

Step-by-Step Device Bridging

1. Start Services with Open Bindings: On your hosting PC or Android tablet, boot the API:
   • Using Pre-compiled Binary (Direct Run):

     ./run.sh
     # OR run the binary directly:
     ./codedroid-api

   • Building from Source (Requires Rust/Cargo):

     cd codedroid_api && cargo run --release

   • Compiling Binary to Root (For Developers):

     ./run.sh --build

     This compiles the API and places it in the root for direct run. In another session, start the Trunk Web IDE specifying bindings:

   cd codedroid_frontend && trunk serve --port 8082 --address 0.0.0.0

2. Locate Local IP Address: Find the hosting device's local routing IP on the network:
   • Android: Run ip addr show wlan0 (looks like 192.168.0.101).
   • macOS: Run ipconfig getifaddr en0.
   • Linux: Run hostname -I.
3. Connect Remote Client: Open Safari or Chrome on your secondary iPad/iPhone and go to http://192.168.0.101:8082.
4. Configure API Routing: Open settings (⚙️) inside the Web IDE and set the Backend Server path to http://192.168.0.101:3030. Tap Test to establish connection.

---

⚙️ LSP Binary Executable Path Resolution

The backend implements custom lookup logic inside utils.rs (resolve_lsp_executable) to resolve compiler LSPs.

 Start LSP Request
│
Does executable exist in PATH?
(using which / where)
├── Yes ──► Return binary command name
└── No
│
Check Termux System Prefix ($PREFIX/bin/)
├── Yes ──► Return path to Termux binary
└── No
│
Check macOS Homebrew Binaries (/opt/homebrew/bin/)
├── Yes ──► Return Homebrew path
└── No
│
Check NPM Global Installations (~/.npm-global/bin/)
├── Yes ──► Return global NPM binary
└── No
│
Run default name fallback

---

🔮 Upcoming Features & Roadmap

We are expanding CodeDroid into a full-featured desktop-class editor on mobile:

• Origin Private File System (OPFS): Integrate the File System Access API to edit local folders on your phone directly from the browser.
• Collaborative Sessions: Support multi-client peer-to-peer pairing over WebRTC for pair programming.
• Offline Native Compiler Toolchains: Bundle minimal compiler binaries inside wrapper apps to run code completely detached from an external API server.

---

🤝 Contributing

We welcome contributions to CodeDroid. Please check CONTRIBUTING.md for details on making pull requests, code formatting (cargo fmt), and setting up your dev workspace.

---

📄 License

CodeDroid is licensed under the GNU General Public License v3.0.

---

💬 Community Channels

• Discord: Join our Community Server
• Telegram: Join Channel Updates
• YouTube: Watch Video Guides & Features

---

CodeDroid — Because real developers code everywhere.