Shelly

---

See it run

AI reading a runtime error and suggesting the fix in real time

https://github.com/user-attachments/assets/113ec26e-d289-4a06-a6d8-ef48158e874c

No Termux. No root. No remote dev server. A real AI coding CLI — today, OpenAI Codex — invoking on Android, plus an API-backed AI pane that reads terminal output and produces a one-tap fix.

An autonomous agent, scheduled in plain language, that wakes itself to do the work

https://github.com/user-attachments/assets/ab272ae8-c741-4acb-b71d-2da151f50d75

Type @agent and a plain-language instruction. Shelly turns it into a scheduled on-device agent that fires on its own alarm — here it set itself for 16:16, woke up while the screen was off, collected sources with the user's own API key, and wrote a primary-source summary to the Obsidian vault. Observed end-to-end once on a Galaxy Z Fold6 (N=1); cross-OEM and deep-Doze behavior is not yet tested beyond this device — see Status.

---

Why Shelly?

Termux is a terminal. ChatGPT is an AI chat. Replit is a cloud workspace. Desktop AI coding CLIs are desktop-first.

Shelly is the workspace that connects those pieces on the Android device you already carry: local terminal work, app-owned native PTYs, Codex CLI, AI panes, browser/docs, previews, and background API agents.

The copy-paste problem

You're running an AI coding tool in a terminal — Codex, or any other AI CLI. It throws an error. You copy it. You switch to ChatGPT. You paste. You ask "what went wrong?" You read the answer. You copy the fix. You switch back. You paste. You run it.

Seven steps. Every single time.

This is a familiar workflow for developers using CLI-based AI tools. The terminal and the AI live in different worlds, and you are the copy-paste bridge between them.

Shelly puts the terminal and the AI side by side. The AI reads your terminal output automatically.

Say "fix the error on the right". Shelly reads the terminal output, explains the error, and generates an executable command. Tap [Run] and the fix lands directly in the Terminal pane.

No copy. No paste. No tab switching.

Three levels of value:

• Single pane: a native terminal that is faster, smarter, and more usable than Termux alone — with inline content blocks, autocomplete, syntax highlighting, and clickable errors.
• Split panes: terminal + AI side by side — the AI reads what the terminal shows and executes fixes with one tap. No copy-paste bridge needed.
• Full layout: sidebar + up to 4 live panes + agent bar — a mobile IDE. Browse docs in the browser pane, preview code or markdown on the right, use API-backed agents in the background, and keep your terminal front and center.

---

Important Android Notes

• APK is ~800 MB because Shelly bundles real tools, not shims. bash, Node.js, Python 3, git, curl, ripgrep, jq, tmux, vim, less, sqlite3, make, ssh — plus the OpenAI Codex CLI runtime — ship inside the APK. No Termux, no repository server, no package manager bootstrap. First launch extracts the binaries into app-private data.
• All files access is requested on first launch so /sdcard works the way a desktop terminal expects (cd /sdcard/Download, editing files there, etc.). Scoped Storage without this permission silently blocks writes. You can refuse — Shelly still works inside its own sandbox, but /sdcard paths will Permission denied.
• LD_PRELOAD + /system/bin/linker64 is how Shelly runs Linux-layout binaries on Android bionic (SELinux blocks direct execve on app-private ELFs). The wrapper rewrites /bin/X and /usr/bin/X to /system/bin/X and routes app-bundled ELFs through linker64. Source is in modules/terminal-emulator/android/src/main/jni/exec-wrapper.c.
• Not Termux-compatible by design. Shelly does not use Termux packages, Termux paths, or Termux's prefix assumptions. If you already have Termux installed, Shelly still bundles its own copies of everything. No conflict, but also no sharing.

---

Quick Start

Install

Download the current Android APK from GitHub Releases. The rolling android-latest release is the source of truth for the newest Shelly build, and the latest tagged vX.Y.Z release APK is cut from that same build — the exact versionCode, commit, and SHA-256 are live in android-latest/latest.json.

After the first install, Shelly can update itself from inside the app: open the cloud-download button in the top bar or Settings → Updates. Shelly reads the public android-latest/latest.json manifest, compares Android versionCode, enqueues the APK with Android DownloadManager under /sdcard/Download/shelly-update-<versionCode>/, verifies SHA-256, then opens Android's package installer. The system download keeps running if Shelly is backgrounded or restarted. Android still asks you to confirm the install because Shelly is distributed outside the Play Store.

Expo OTA is disabled for release APKs. JS, native, and bundled-tool changes ship together through a new APK so the installed binary and app code stay in sync.

Build from source

git clone https://github.com/RYOITABASHI/Shelly.git && cd Shelly
pnpm install && pnpm android

Requirements:

• Android device
• Node.js 20+ (CI currently builds on Node 20)
• pnpm
• Android NDK 26.1.10909125 (or an Android SDK/Gradle setup that resolves that pinned NDK)

Expo Go is not supported — Shelly uses native Kotlin/C modules.

Termux is not required. Shelly ships with bash, Node.js, Python 3, git, curl, sqlite3, tmux, vim, less, jq, make, and ripgrep. For tools beyond the bundled set, Termux can be used alongside Shelly.

First launch

On first launch Shelly asks for All files access so the terminal can read scripts in /sdcard/Download and anywhere else on your phone. Tap Allow and you're done — source /sdcard/Download/foo.sh just works. Shelly is distributed through GitHub Releases for now; Play Store / F-Droid submission is still future work.

Configure AI

After that, open Settings → API Keys (or run shelly config from the terminal pane) to paste API keys for Gemini, Cerebras, Groq, Perplexity, OpenAI-compatible local servers, or other explicit API providers. Keys are stored in expo-secure-store and never written to logs.

Sign in

Shelly's foreground AI CLI is Codex. Everything else is an API provider you configure with a key.

Surface	How to sign in	Notes
Codex CLI (ChatGPT subscription)	Run codex, or codex-login --open directly	The supported foreground CLI. If ~/.codex/auth.json is missing or invalid, the codex wrapper starts Shelly's device-code login, opens the OpenAI device-code page in the in-app Browser Pane, writes ~/.codex/auth.json (mode 0600) on success, then launches the normal Codex TUI. No OpenAI API key required — this rides your ChatGPT subscription.
API providers (Gemini, Cerebras, Groq, Perplexity, local)	Settings → API Keys or shelly config	Paste a key per provider for AI-Pane / @mention / @team / background-agent use. Keys live in expo-secure-store. Local/OpenAI-compatible servers need only a base URL.

Codex login note. codex /login inside the REPL is not the supported path on Shelly. Use bare codex and let Shelly's wrapper launch device-code auth, or run codex-login --open from bash.

Bundled Shelly commands

Command	Use
codex	Launch the foreground Codex TUI in the native terminal. If auth is missing, Shelly starts the device-code login flow first.
codex-login --open	Start ChatGPT subscription device-code auth and open the verification page in Shelly's Browser Pane.
shelly-doctor	Check shell/native binary presence, bundled Codex binaries, JS dispatcher, local LLM endpoints, and Codex auth file presence.
shelly-codex-diagnose	Run deeper Codex smoke/canary/edit/patch diagnostics.
shelly-update-clis codex --check-only	Probe the active Codex runtime. Runtime installs are normally driven by the Updates UI.
shelly-cs / cs	GitHub Codespaces helper commands.

---

Runtime model

Shelly's headline advantage is the runtime itself: a native PTY and a managed Codex CLI running in the same on-device shell as your files, with API-backed agents layered on top — not a WebView terminal, not a remote IDE client.

If your AI coding CLI workflow stalled in Termux, proot, or another Android terminal setup, Shelly gives you a maintained on-device environment built around the constraints of real Android devices (bionic libc, linker64 exec rules, SELinux on app_data_file).

No fragile terminal stack. No WebView terminal crashes. No copy-paste-driven workflow.

• Native execution path — Codex runs through Shelly's app-owned native PTY (JNI forkpty), not a remote bridge or socket terminal.
• Managed latest, not blind latest — Shelly ships a pinned Codex runtime in each APK, and the Updates UI can install a newer verified Codex runtime from the rolling codex-runtime-latest release without waiting for the next APK.
• Visible state — the app can show recent terminal logs, so version drift and startup failures are easier to debug on the device itself.
• Compliance boundary — Codex is a foreground, user-controlled termin