Show HN: Polpo – Control Claude Code (and other agents)…

Polpo is an open-source mobile controller for AI coding agents. It runs a lightweight server on your machine and gives you a phone-friendly dashboard to manage sessions, send prompts, approve tool calls, and review plans.We just released v1.1.0 with support f…

Polpo lets developers send prompts, see responses, and control Claude Code, OpenAI Codex CLI, Google Gemini CLI, OpenCode, and Pi coding agent sessions from any mobile device over VPN, Wi-Fi, LAN, or a public tunnel. Help us test! Claude Code support is stable and battle-tested. Support for Codex, Gemini, OpenCode, and Pi is functional but still being stabilized — edge cases in multi-turn, auto-discovery, and session resume may exist.

If you use any of these agents, we'd love your feedback: open an issue with reproduction steps and we'll fix it fast. AI coding sessions can run for minutes while reading files, writing code, and running tests. During that time, developers are tethered to their terminal waiting to approve tool calls, review output, or send the next prompt. Polpo frees you from the keyboard. Grab a coffee, kick off a refactor while waiting for a train, or review tool calls from an airport lounge – your phone becomes a full remote control for Claude Code, Codex, Gemini, OpenCode, and Pi.

You see every tool call as it happens, approve or reject actions with a tap, send follow-up prompts, and abort tasks when something goes wrong. All in real time, from any network. The dashboard shows active sessions, past session history, and lets you send prompts, watch tool calls, approve or reject actions, and abort tasks. Security: Running on localhost alone does not protect you. Use –tunnel with auth for internet access, or connect via VPN for private access.

Read the Security section before exposing Polpo to any network. Note: Polpo streaming is near real-time, not strictly real-time. Auto-discovery relies on filesystem events (fs.watch) which have inherent OS-level latency; JSONL/JSON watchers debounce file changes; agents using one-shot process invocation (Codex, Gemini) accumulate deltas before flushing; and when fs.watch is unavailable (e.g. inotify limit exhaustion), the system falls back to periodic polling.

In practice, latency is typically under one second, but it is not zero. Polpo gives your phone full control over coding agents running on your machine: sending prompts, approving tool calls, reading conversation output. Securing this access is critical. Use –tunnel with an auth mode. This exposes Polpo via a public URL with authentication enabled. Best when you need access from cellular, a different network, or when you don't control the network.

Connect your phone to the same network as your machine via a VPN (WireGuard, Tailscale, ZeroTier, etc.), then access Polpo directly at http://<machine-ip>:7890. No tunnel, no public URL. The connection stays private within your VPN. Running on localhost does not make Polpo safe. A malicious webpage you visit in your browser can open a WebSocket to ws://localhost:7890 and read all session data (tool calls, file contents, API keys) via a CSRF attack.

Polpo mitigates this with Origin header validation on both WebSocket and API connections: the server rejects any request whose Origin doesn't match its own host. This blocks cross-origin attacks from malicious pages while allowing legitimate connections from the Polpo dashboard and agents. Auth is auto-enabled when using –tunnel. For LAN or VPN deployments, you can enable it manually with –auth <mode>.

Add –tunnel to expose the hub over the internet. A public URL and QR code are printed for your phone to scan – no VPN or same-network requirement. Auto-detect tries cloudflared first, then falls back to localtunnel. ngrok and SSH require explicit –tunnel <provider> since they need configuration. The session command spawns a CLI process with JSON streaming and gives your phone full bidirectional control.

Use –agent to select the agent type. When a session runs in default permission mode, an MCP permission server handles tool approval. When Claude needs to run a tool that requires permission, the request appears on your phone as a banner with three options: When auto-approve is active, a green "Auto-approve ON" indicator appears with a "Stop" button to disable it. Plans and questions always require review, even when auto-approve is on.

When Claude proposes a plan (ExitPlanMode), the full plan content is rendered with markdown (headings, tables, code blocks, lists) in a collapsible panel. When Claude asks questions (AskUserQuestion), the options appear as tappable radio buttons or checkboxes with a free-text "Other" fallback. The dashboard automatically discovers past sessions from ~/.claude/projects/ (Claude Code), ~/.codex/sessions/ (Codex), ~/.gemini/tmp/ (Gemini), ~/.local/share/opencode/opencode.db (OpenCode), and ~/.pi/agent/sessions/ (Pi) and displays them as cards with the session's first prompt as the title.

Each card shows an agent type badge (Claude, Codex, Gemini, OpenCode, or Pi). Tap a session to view its full conversation history, or resume it to continue working from your phone. Sessions are loaded from JSONL/JSON files (or SQLite for OpenCode) and deduplicated to show clean conversation threads. Use the ?source=claude|codex|gemini|opencode|pi|all query parameter on the /api/sessions endpoint to filter by agent type.

Claude, Codex, Gemini, and Pi use event-driven fs.watch(). OpenCode uses SQLite polling via sqlite3 CLI (requires sqlite3 to be installed). Auto-discovery works with any interface that writes JSONL/JSON session files (terminal CLI, VS Code extension, web). Gemini CLI must be authenticated (run gemini once to set up API key or Google account auth). OpenCode must be configured with at least one provider (run opencode once to set up).

Auto-discovery requires sqlite3 CLI (apt install sqlite3 / brew install sqlite3). Hooks are optional — auto-discovery handles session detection and conversation sync without them. Hooks add two capabilities: Add the output to ~/.claude/settings.json. The bridge daemon auto-discovers the server token from ~/.config/polpo/server.json — no manual token passing needed. Note: Shell hooks from settings.json work with the claude CLI.

The VS Code extension uses its own internal hook mechanism and does not execute shell hooks. For VS Code sessions, auto-discovery provides full conversation sync without hooks. Auto-discovered and hook instances are read-only — they mirror conversations from session files on disk, but have no backing agent process to accept prompts. Tap Take Over to spawn a real agent process (claude –resume, codex exec resume, gemini –resume, or pi –session) that resumes the session with full prompt capability.

The existing conversation history is preserved in the new instance. This is the same resume mechanism used by the Claude Code VS Code extension when selecting a previous conversation — there is no long-lived process to reconnect to; the CLI replays context from transcript files on each resume. When you return to your terminal, run claude –continue (Claude) or start a new session (Codex/Gemini) to reload the conversation.

In VS Code, reload the window (Ctrl+Shift+P → "Reload Window") to pick up messages sent from Polpo — the VS Code extension caches conversations in memory and only re-reads session files on reload. Search past conversations across all supported agents directly from the dashboard. Type a query and tap the search button (or press Enter) to find matching messages. Skills are a Claude Code-specific feature.

The skills manager is accessible from the detail view of any Claude instance — tap the gear icon in the header to open it. Skills are stored at ~/.agents/skills/ and symlinked into ~/.claude/skills/ for use by Claude Code. Runs unit tests with Node's built-in test runner. Tests cover authentication (token, PIN, TOTP, sessions, middleware), instance manager, tunnel provider logic, session JSONL/JSON parsing, JSONL/JSON file watcher (messages, status events, dedup), session scanner (Claude/Codex/Gemini/Pi auto-discovery, idle detection, project watching), Codex agent (event translation, hub messages, multi-turn), OpenCode agent (event translation, delta accumulation), Pi agent (RPC event handling, delta accumulation, tool call streaming), Codex scanner (Codex session discovery), Pi scanner (Pi session discovery, slug parsing), agent factory (agent type routing), and skills API (frontmatter parsing, search output parsing, input validation).

See docs/diagrams.md for auth, tunnel, session, auto-discovery, takeover, and hook flow diagrams. THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, COPYRIGHT HOLDERS, MARCO PENNELLI, OR PUGLIATECHS APS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Use this software at your own risk. The author and the organization assume no responsibility for any damages, data loss, security incidents, or other consequences resulting from the use or misuse of this software.

Summary

This report covers the latest developments in android. The information presented highlights key changes and updates that are relevant to those following this topic.

---