PocketShell: A voice-first tmux client that turns your phone into a terminal for AI coding agents
Voice-first, tmux-native, agent-aware Android SSH client
At a glance
- What is it?
- PocketShell is an Android-only SSH client built around tmux control mode, with a server-side helper that keeps provider credentials off the phone. It targets developers who want to drive Claude Code, Codex, or similar agents from a phone, but its version-locking and single-user focus demand a careful setup.
- Who is it for?
- Adopt PocketShell if you are a solo developer who lives in tmux and wants to drive AI coding agents from an Android phone without exposing provider credentials. Skip it if you need multi-user support, iOS, or a stable API across versions: the project deliberately breaks compatibility and requires the app and helper to match exactly.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Kotlin, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- alexeygrigorev/pocketshell39 ★ · +10
| Repository | 2026-08-26 | 2026-11-15 |
|---|---|---|
| alexeygrigorev/pocketshell | 29 | 39 |
10 Stars in the last 81 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem: a phone-shaped interface for a desktop tmux workflow
PocketShell solves a specific mismatch: you have a development workstation you reach over SSH, you keep your work in tmux sessions, and you want to continue from a phone. A normal SSH client on Android gives you a terminal, but it does not understand tmux layouts, and it certainly does not understand that a pane is running an AI coding agent. PocketShell attaches to tmux in control mode and renders one pane at a time, which is a deliberate choice: a tiled tmux layout is unreadable on a small screen, so the app throws away the tiling and gives you a single pane with swipe or tap navigation. The target user is a solo developer, likely the maintainer himself, who uses this daily. The README says it is the maintainer's primary way of working on a dev box from a phone. That is a narrow audience, and the project does not pretend otherwise.
How it works: tmux control mode plus a Python helper on the host
The architecture splits responsibilities between the phone and the dev box. The Android app connects over SSH and attaches to tmux with `tmux -CC`, which is control mode. In control mode, tmux emits a structured protocol of events and commands, letting the app render a terminal emulator for one pane at a time. The app also detects whether the visible pane is running an agent like Claude Code, Codex, OpenCode, or Grok Build. When it detects one, it opens a Conversation view that shows the agent's turns, tool calls, and output, and it sends composer input back into the pane. The server-side piece is a small Python helper also named `pocketshell`. It handles provider usage and quota, the session tree, repo browsing, env files, jobs, and QR sharing. The key design point is that provider credentials never move onto the phone; they stay on the box, and the helper mediates access. This is a meaningful security decision, because the phone only ever sees the SSH connection and the tmux output, not API keys for the AI providers.
Installation: a debug APK and a version-matched PyPI helper
Installation has two parts, and both must be the same version. On the phone, you download a debug APK from the GitHub Releases page, such as `pocketshell-0.4.44-debug.apk`, and install it manually or with `adb install -r`. The app requires Android 8.0 (API 26) or newer. On the dev box, you install the helper with `uv tool install pocketshell` or `pipx install pocketshell`, and you can pin to a specific release like `pocketshell==0.4.44`. If you want to generate host QR codes from the box, you add the QR extra: `uv tool install pocketshell --with "qrcode[pil]"`. The README warns that the app does not open a login shell, so `~/.local/bin` must be on `PATH` for non-interactive SSH. That is a concrete gotcha: if your shell profile sets up PATH only for interactive sessions, the helper will not be found. Host configuration can be manual, with fields for name, hostname, port, username, and SSH key, or via QR code. The QR route is faster and can carry the private key, which the README explicitly warns is a visible secret on the screen.
Voice input and agent awareness: the actual mechanisms
Voice input is not a gimmick here; it is the primary input method. The composer uses OpenAI Whisper and the Android speech recognizer to turn dictation into commands or agent prompts. There is also a key bar that adds Esc, Tab, Ctrl, Alt, and arrows above the keyboard, which is essential for terminal work where those keys are not on a phone keyboard. Per-host snippets and prompt templates reduce typing further. Agent awareness is the more interesting part. The app detects an agent in the visible tmux pane and switches to a Conversation view by default, with a Terminal tab still available. The reply composer stays on screen, so you can send a prompt without switching to the terminal. This is a different interaction model from a plain SSH client: you are not just typing into a shell, you are monitoring and steering an agent that is already running.
A real limitation: version locking and breaking changes
The most significant limitation is the version-locking requirement. The README states that the Android app and the host helper must be on the same version, and that a newer app talking to an older helper can hang on connect. That is a hard failure mode, not a warning. The project also takes hard cuts on breaking changes rather than carrying compatibility shims, because there is no install base to keep happy, as documented in decision D22. This means every release can break the connection between app and helper. For a solo developer who controls both ends, this is acceptable. For anyone who wants to share a dev box with colleagues or maintain a fleet of devices, it is a problem. There is no mention of a stable API or a migration path. You must be prepared to update both sides in lockstep, and if you forget, you get a hang, not a friendly error.
The alternative: a plain SSH client with tmux on the phone
The obvious alternative is to use a regular SSH client like Termius or JuiceSSH on Android and run tmux in a normal terminal session. That approach does not use control mode, so you see the full tiled layout, which is hard to read on a phone. You also lose agent awareness and voice input. The difference in approach is fundamental: a plain SSH client treats the phone as a dumb terminal, while PocketShell treats it as a purpose-built controller for tmux and AI agents. The trade-off is that a plain SSH client works with any server and any tmux version, and it does not require installing a Python helper or matching versions. If you only need to run a few commands or check a log, a plain client is simpler. If you want to drive a long-running agent session from a phone, PocketShell's Conversation view and composer are genuinely different. The README does not mention any alternative, so this comparison is based on what the project does differently.
Maintenance and upgrade cost: what you sign up for
The maintenance cost is directly tied to the version-locking policy. Every release of the app must be matched by a release of the PyPI helper, and the README explicitly says to keep them on the same version. The release history shows a cadence of roughly two weeks between v0.4.43, v0.4.44, and v0.4.45, so updates are frequent. You will need to update both sides each time, or risk a hang on connect. The helper is installed via `uv` or `pipx`, so upgrading is a single command, but you have to remember to do it. The project is not archived and has recent activity, so maintenance is ongoing, but the license is listed as unknown. That is a gap: you cannot assume open-source licensing terms for redistribution or modification. The README does not state a license, so if you plan to fork or embed any part of it, you need to check the repository directly. The project is also Android-only and single-user, so there is no server-side multi-tenant management to learn, but there is also no way to share a box with a team.
Editorial conclusion
Adopt PocketShell if you are a solo developer who lives in tmux and wants to drive AI coding agents from an Android phone without exposing provider credentials. Skip it if you need multi-user support, iOS, or a stable API across versions: the project deliberately breaks compatibility and requires the app and helper to match exactly. Before adopting, verify that your SSH host can run the `pocketshell` Python helper non-interactively, that your tmux version supports control mode, and that you are comfortable installing a debug APK from GitHub Releases. Also confirm that your agent of choice (Claude Code, Codex, OpenCode, Grok Build) is detectable in a tmux pane; the README lists these four but not others. Test the connection with a fresh tmux session first, because a version mismatch can hang on connect.
Frequently asked questions
What is the point of a shell jacket?
This repository is about software, not clothing. PocketShell is a voice-first Android SSH client. Its released 0.5.x Kotlin application lives on a separate release branch, and the default branch carries an untagged 0.6.0 rewrite built with Vue 3, TypeScript and Capacitor.
What are jackets with inside pockets called?
Nothing here concerns garments. What the repository documents is a build pipeline: a recursive clone, a frozen lockfile install, a JavaScript unit gate script and a debug assembly script, requiring Node.js, a specific package manager, JDK 21 and a particular Android SDK platform.
What does "waterproof shell" mean in PocketShell?
Here shell means a terminal shell, and the app renders one. It depends on a terminal emulator with a fit addon inside the Capacitor web view, and the default branch currently shows a sample terminal with offline host and workspace states rather than a live connection to any SSH host.
What's the difference between a rain jacket and a rain shell?
The repository addresses no clothing question. What it does document is the state of its rewrite: the development branch builds the web app and a debug package, runs unit tests and checks a Docker fixture, while emulator parity journeys, scheduled verdicts and release packaging remain owned by the existing Android gates until a tracked issue provides validated replacements.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/alexeygrigorev-pocketshell)Star history chart for your README
[](https://hysenlabs.com/projects/alexeygrigorev-pocketshell)Was this useful?