pocketshell

What PocketShell does

PocketShell is described as a voice-first, tmux-native, agent-aware Android SSH client. It connects a phone to the developer workstation the user already has over SSH, attaches to tmux sessions in control mode, and gives a phone-shaped way to drive shells and AI coding agents without typing everything by hand. The README states the app is built for one job: keep working on a dev box from a phone. Long-lived state lives on the dev box in tmux and a small server-side pocketshell helper, and the app reconnects when brought back to the foreground. The status section says the project is in active development and dogfooded daily by the maintainer, and that it is Android-only and single-user. The design takes hard cuts on breaking changes rather than carrying compatibility shims, because there is no install base to keep happy. A download is offered from the releases page as a debug APK. The listed capabilities include tmux-native sessions that attach with control mode and render one pane at a time in a real terminal emulator, agent awareness that detects Claude Code, Codex, and OpenCode in the visible pane and shows a conversation view, and voice-first input that turns dictation into commands or agent prompts using OpenAI Whisper and the Android speech recognizer.

Host management and setup

The README explains how a user adds and connects to hosts. Host management covers saving SSH hosts, importing or generating credentials, unlocking credential passphrases biometrically, and importing a host from a QR code. A server-side helper named pocketshell is installed once per dev box with a tool installer, and it handles usage and quota, repo browsing, environment management, and jobs so provider credentials never move onto the phone. The app can be installed by downloading the latest debug APK from the releases page and opening it, or by using adb. Requirements are Android 8.0, API 26, or newer. Configuring a host can be done manually by tapping a plus button and filling a form with name, hostname or IP, port, username, and SSH credential, or by scanning a QR code generated on the dev box with the qr-share command. The QR payload can include the private credential, which the README warns is a visible secret on screen, so it advises generating and scanning in private and deleting any PNGs afterward. Connecting taps a host, checks the helper version, discovers watched folders and tmux sessions, and opens or creates a tmux session. The user then has the mic and composer, a shortcut bar, snippets, a slash-command palette, a conversation tab, a file browser, and a port-forward panel. Saved credentials are managed inside the app, and the README states provider secrets stay on the dev box rather than on the phone.

How it fits together

The README lays out the architecture as an Android phone talking SSH to a dev box, with tmux control mode on one side and a pocketshell helper on the other. Load-bearing choices are spelled out. The app uses tmux control mode instead of screen-scraping, shows one visible pane at a time instead of a tiled tmux layout, keeps server-side helpers so no provider credentials live on the phone, and follows a foreground-first model where the app does not schedule background phone work but reconnects when brought forward, with a short grace window so quick app swaps do not tear down the connection. The scoped exception is port forwarding, which uses a foreground service while tunnels are active. The repository layout shows an app module for the Android application and shared modules for the sshj wrapper, connection control, port forwarding, tmux parsing, the terminal emulator, agent detection, an in-app assistant, usage parsing, storage, and voice. The tools directory holds the server-side Python helper published to PyPI, and tests use a deterministic Docker SSH fixture. The development section lists JDK 17, the Android SDK, an emulator image, Docker with Compose, and a local properties file pointing at the SDK. Common commands wrap gradle through a cgroup runner for assemble, test, and check, with connected tests and a Docker emulator runbook documented for contributors.

Editorial conclusion

PocketShell has no SPDX license set in the repository metadata, and its most recent commit was on 2026-08-26. The app is hosted at github.com/alexeygrigorev/pocketshell.