CC Pocket: run Codex and Claude from your phone through a local WebSocket bridge

The problem CC Pocket solves: agent sessions that outlive your desk

Long-running coding agents spend most of their time waiting for a human. A prompt goes out, the model plans, then it stops and asks for approval, and nothing moves until someone answers. That is tolerable at a desk and awkward everywhere else. CC Pocket exists so the answering half happens on a phone, while the executing half stays on the machine that owns the repository, shell and agent CLI.

The README frames the product as a chat UI made for a phone: start a task, approve the next step, review the result, then pick the same work up on a tablet or Mac. The audience is therefore narrow and specific. It is for people who already run Codex or Claude locally and want a remote control, not for people looking for a hosted coding environment. If your agents run in CI or inside someone else's cloud, the bridge model buys you nothing.

One detail in the README is worth reading as a design statement rather than marketing: your code stays on your own machine instead of moving into a hosted IDE. Everything else in the project follows from that constraint, including the parts that are inconvenient.

How the Bridge Server and the app split the work

The architecture is two processes and one socket. The README draws it as `CC Pocket app <-> Bridge Server on your machine <-> Codex / Claude`. The app renders chat, files, diffs and git state. The Bridge Server runs on the host that has access to your projects, shell, git repository and agent CLI, and it is the only component that talks to the agents.

That split explains several behaviours. Sessions can be resumed from the CLI or the app, because the agent process and its session history live on the host, not in the phone. The app can browse files and inspect code and image diffs because the bridge exposes the working tree. Git operations, including staging, committing, pushing and reverting, are executed by the bridge on your machine. Git worktrees are supported so parallel tasks do not collide in one directory.

The connection layer is a WebSocket, either `ws://` or `wss://`. On a local network the app can find the bridge by QR code, mDNS discovery or a manually entered URL. Away from that network the README recommends Tailscale and gives the target form `ws://<host-tailscale-ip>:8765`, which tells you the default port the bridge listens on. Weak networks are handled by queueing outgoing messages while offline, resending after reconnection, and recovering missed streaming updates, but the README is explicit that new agent requests need a connection. Approvals and prompts you already sent can survive a tunnel; a fresh task cannot start in one.

Installing the bridge and starting a first session

The install path assumes the agent side already exists. You need at least one agent CLI on the machine that will run sessions, either Codex or Claude, plus Node.js 20.18.1 or newer on that same machine. The README does not describe a bridge-free mode, so this host requirement is not optional.

The bridge itself is published on npm and started with npx:

npx @ccpocket/bridge@latest

When it starts, the bridge prints a QR code. Install CC Pocket on the phone and scan that code, which is the pairing step. Then pick a project, choose Codex or Claude, and start a session from the app. If you would rather not run npx by hand every time, the README shows a setup subcommand that registers the bridge as a background service:

npx @ccpocket/bridge@1 setup

Service setup supports macOS launchd and Linux systemd, according to the README. Persisted service settings such as `BRIDGE_ALLOWED_DIRS` are documented in the Bridge package README at `packages/bridge/README.md#configuration`, which is where to look before locking the bridge into a service. For remote access, the documented sequence is to install Tailscale on both the host and the phone, join the same tailnet, and connect to `ws://<host-tailscale-ip>:8765`.

Client installs differ by platform. iOS and iPadOS come from the App Store, Android from Google Play. macOS ships as a `.dmg` from GitHub Releases under tags matching `macos/v*`, and is also available through Homebrew Cask as `brew install --cask cc-pocket`. Linux builds are `.tar.gz` files tagged `linux/v*`, with a community-maintained AUR package `cc-pocket-bin`. Windows builds are `.zip` files tagged `windows/v*`.

Authentication, permissions and the rough edges

The most consequential limitation is documented rather than hidden. Claude sessions use `ANTHROPIC_API_KEY` by default. Subscription authentication requires explicit bridge opt-in with `BRIDGE_ALLOW_CLAUDE_OAUTH=1`, and the README explains why: Anthropic's current official guidance has an unclear scope for this architecture. Read that as the maintainers declining to make a decision for you. If you rely on a Claude subscription rather than an API key, you are enabling a mode the project itself describes as uncertain, and there is a troubleshooting document at `docs/auth-troubleshooting.md` for when it misbehaves.

Platform maturity is uneven. macOS, Linux and Windows builds exist, but the README states that Linux and Windows remain experimental because the project does not have the same continuous verification coverage for those environments. The Linux client is labelled experimental in the install table as well. On macOS there is a separate system-level requirement: screenshot capture needs Screen Recording permission granted to the terminal app running the Bridge Server. If you launch the bridge from a terminal you later replace, that permission does not follow automatically.

The bridge is also a remote execution surface by construction. It exposes shell, git and file access over a socket. The README points to `BRIDGE_ALLOWED_DIRS` as the setting that constrains which directories are reachable, which suggests the sensible default is to set it rather than accept whatever the bridge does unconfigured. The README does not document rollback of a bridge upgrade, and it does not describe what happens to in-flight sessions when the bridge restarts, so treat both as unverified.

Where CC Pocket is the wrong tool, and what to compare it against

CC Pocket assumes a persistent host you own. If your laptop sleeps, the bridge sleeps with it, and the README's answer is an always-on host with the bridge registered as a service. Anyone who wants to close the lid and keep working should look elsewhere.

The obvious alternative is a browser-based remote development environment such as GitHub Codespaces or Gitpod, where the workspace runs in someone else's infrastructure and is reachable from any browser with no bridge process to keep alive. The difference is not cosmetic. In that model your repository is cloned into a hosted machine, the agent runs there, and the vendor's network and access controls sit between you and the code. CC Pocket inverts both properties: nothing is hosted, and the security boundary is a WebSocket on your own network or tailnet that you configure yourself. If your constraint is that source code must not leave machines you control, the hosted option is disqualified and CC Pocket's operational burden is the price. If your constraint is that you do not want to administer anything, the hosted option wins and CC Pocket is the wrong choice.

A second comparison is simply using the agent CLI over SSH from a phone terminal. That gives you the same execution location with none of the app layer, and no approval UI, diff viewer, image attachments or offline queueing. CC Pocket is worth its bridge only if those surfaces are what you actually lack.

Forking it, licence terms and upgrade cost

The repository is MIT licensed, and the README treats that as a feature rather than a formality. It explicitly invites using CC Pocket as a starting point for a custom agent workflow: building an internal client that combines Codex or Claude with a team's Jira, Linear, GitHub or private REST APIs, removing surfaces you do not need, or reusing the bridge sync layer, approval flow, prompt history, git operations, file browsing and image and diff viewers instead of rebuilding them. MIT permits that, including in closed internal tools, provided you keep the copyright and permission notice. That is a general property of the licence, not legal advice, and the repository also carries a SECURITY.md and a PRIVACY_POLICY.md worth reading before you ship a fork.

The upgrade story is more mixed. Releases are versioned per platform, with the most recent set tagged `macos/v1.131.0+248`, `linux/v1.131.0+248` and `windows/v1.131.0+248`, all published on 2026-09-14. The bridge is versioned separately on npm, and the README's own examples pin differently, using `@latest` for a manual start and `@1` in the service setup command. Those two will diverge over time. App and bridge are separate upgrade paths, so a mismatch is possible and the README does not describe a compatibility matrix between bridge and client versions. The repository also contains a CHANGELOG.md and a set of Shorebird patch scripts for Android and iOS, which indicates the maintainers ship over-the-air patches rather than relying only on store review cycles. The last push to the default branch was on 2026-09-14.

Editorial conclusion

Adopt CC Pocket if your agents already run on a machine you control and you want approvals, diffs and git operations on a phone without moving code into a hosted IDE. Skip it if you want a managed service, since you must run Node.js 20.18.1 or newer and the bridge yourself, and Linux and Windows builds are labelled experimental. Before trusting it with a repository, confirm on the host that the bridge binds where you expect, that BRIDGE_ALLOWED_DIRS is set the way you want, and whether Claude should use ANTHROPIC_API_KEY or the opt-in BRIDGE_ALLOW_CLAUDE_OAUTH=1 path.

Frequently asked questions

Official sources

1. K9i-0/ccpocket on GitHub
2. License: MIT
3. Project website
4. README
5. Releases