CC Pocket

CC Pocket lets you start and run Claude Code and Codex sessions entirely from your phone. No laptop needed — just open the app, pick a project, and code from anywhere.

日本語版 README

CC Pocket is not affiliated with, endorsed by, or associated with Anthropic or OpenAI.

Why CC Pocket?

AI coding agents are getting autonomous enough to write entire features on their own. Your role shifts from writing code to making decisions — approve this tool, answer that question, review the diff.

Decisions don't need a keyboard. They need a screen and a thumb.

CC Pocket is built for this workflow: start a session from your phone, let your mac's Claude Code or Codex do the heavy lifting, and make decisions from wherever you are.

Who It's For

CC Pocket is for people who already rely on coding agents and want an easier way to stay in the loop when they are away from the keyboard.

• Solo developers running long agent sessions on a Mac mini, laptop, or dev box
• Indie hackers and founders who want to keep shipping while commuting, walking, or away from their desk
• AI-native engineers juggling multiple sessions and frequent approval requests
• Self-hosters who want their code to stay on their own machine instead of a hosted IDE

If your workflow is "start an agent, let it run, step in only when needed," CC Pocket is built for that.

Why People Use It

• Start or resume sessions from your phone once your Bridge Server is reachable
• Handle approvals quickly with a touch-first UI instead of a terminal prompt
• Watch streaming output live including plans, tool activity, and agent responses
• Review diffs more easily with syntax-highlighted code changes and image diff support
• Write better prompts with Markdown, auto-completing bullet lists, and image attachments
• Track multiple sessions with project grouping, search, and approval badges
• Get notified when action is needed with push notifications for approvals and task completion
• Connect however you prefer with saved machines, QR codes, mDNS discovery, or manual URLs
• Manage a remote Mac over SSH for start, stop, and update flows when using launchd

CC Pocket vs Remote Control

Claude Code's built-in Remote Control hands off an existing terminal session to your phone — you start on your Mac and continue from mobile.

CC Pocket takes a different approach: sessions start on your phone and run to completion there. Your Mac works in the background; your phone is the primary interface.

	Remote Control	CC Pocket
Session origin	Start on Mac, hand off to phone	Start on phone
Primary device	Mac (phone joins later)	Phone (Mac runs in background)
Use case	Continue a desktop task on the go	Start coding from anywhere
Setup	Built into Claude Code	Self-hosted Bridge Server (open-source)

What this means in practice:

• You can start a brand-new session and run it entirely from your phone
• You can reopen past sessions from history stored on your Mac
• You cannot attach to a live session that was started directly on your Mac

How It Works

1. Install and run the Bridge Server on the machine where Claude Code or Codex CLI is installed.
2. Connect the mobile app to that Bridge Server.
3. Start sessions, answer agent questions, approve tools, and review changes from your phone.

Your coding session stays on your own machine and flows through your own Bridge Server.

Quick Start

1. Install a CLI Provider

Install at least one of these on the host machine:

• Claude Code CLI
• Codex CLI

You also need Node.js 18+.

2. Start the Bridge Server

# Run directly with npx
npx @ccpocket/bridge@latest

# Or install globally
npm install -g @ccpocket/bridge
ccpocket-bridge

By default, the Bridge Server listens on ws://0.0.0.0:8765 and prints a QR code you can scan from the app.

Optional health check:

npx @ccpocket/bridge@latest doctor
# or
ccpocket-bridge doctor

3. Install the Mobile App

     

4. Connect

Method	Best for
Saved Machines	Regular use with reconnects, status checks, and favorites
QR Code	Fastest first-time setup
mDNS Auto-Discovery	Same-network discovery without typing IPs
Manual Input	Tailscale, remote hosts, or custom ports

Examples:

• ws://192.168.1.5:8765
• ws://100.x.y.z:8765 over Tailscale
• ccpocket://connect?url=ws://IP:PORT&token=API_KEY

5. Start a Session

In the app, choose a project and permission mode, then start a Claude Code or Codex session.

Permission Mode	Behavior
Default	Standard interactive mode
Accept Edits	Auto-approve file edits, ask for everything else
Plan	Stay in planning mode until you approve execution
Bypass All	Auto-approve everything

You can also enable Worktree to isolate a session in its own git worktree.

Worktree Configuration (.gtrconfig)

When starting a session, you can enable Worktree to automatically create a git worktree with its own branch and directory. This lets you run multiple sessions in parallel on the same project without conflicts.

Place a .gtrconfig file in your project root to configure file copying and lifecycle hooks:

Section	Key	Description
[copy]	include	Glob patterns for files to copy (e.g. .env, config files)
[copy]	exclude	Glob patterns to exclude from copy
[copy]	includeDirs	Directory names to copy recursively
[copy]	excludeDirs	Directory names to exclude
[hook]	postCreate	Shell command(s) to run after worktree creation
[hook]	preRemove	Shell command(s) to run before worktree deletion

Tip: Adding .claude/settings.local.json to the include list is especially recommended. This carries over your MCP server configuration and permission settings to each worktree session automatically.

Example .gtrconfig

[copy]
# Claude Code settings (MCP servers, permissions, additional directories)
include = .claude/settings.local.json

# Speed up worktree setup by copying node_modules
includeDirs = node_modules

[hook]
# Restore Flutter dependencies after worktree creation
postCreate = cd apps/mobile && flutter pub get

Sandbox Configuration (Claude Code)

When sandbox mode is enabled from the app, Claude Code uses its native .claude/settings.json (or .claude/settings.local.json) for detailed sandbox configuration. No Bridge-side config is needed.

See the Claude Code documentation for the full sandbox schema.

Ideal Use Cases

• An always-on Mac mini running the agent while you monitor from your phone
• A lightweight review loop on the go where the agent codes and you approve commands or answer questions as needed
• Parallel sessions across projects with one mobile inbox for pending approvals
• Remote personal infrastructure over Tailscale instead of exposing ports publicly

Remote Access and Machine Management

Tailscale

Tailscale is the easiest way to reach your Bridge Server outside your home or office network.

1. Install Tailscale on your host machine and phone.
2. Join the same tailnet.
3. Connect to ws://<host-tailscale-ip>:8765 from the app.

Saved Machines and SSH

You can register machines in the app with host, port, API key, and optional SSH credentials.

When SSH is enabled, CC Pocket can trigger these remote actions from the machine card:

• Start
• Stop Server
• Update Bridge

This flow is intended for macOS hosts using launchd.

Service Setup

The setup command automatically detects your OS and registers the Bridge Server as a managed background service.

npx @ccpocket/bridge@latest setup
npx @ccpocket/bridge@latest setup --port 9000 --api-key YOUR_KEY
npx @ccpocket/bridge@latest setup --uninstall

# global install variant
ccpocket-bridge setup

macOS (launchd)

On macOS, setup creates a launchd plist and registers it with launchctl. The service starts via zsh -li -c to inherit your shell environment (nvm, pyenv, Homebrew, etc.).

Linux (systemd)

On Linux, setup creates a systemd user service. It resolves the full path to npx at setup time so that nvm/mise/volta-managed Node.js works correctly under systemd.

Tip: Run loginctl enable-linger $USER to keep the service running after logout.

Platform Notes

• Bridge Server: works anywhere Node.js and your CLI provider work
• Service setup: macOS (launchd) and Linux (systemd)
• SSH start/stop/update from the app: macOS host with launchd setup
• Window listing and screenshot capture: macOS-only host feature
• Tailscale: optional, but strongly recommended for remote access

If you want a clean always-on setup, a Mac mini or a headless Linux box is the best-supported host environment right now.

Host Configuration for Screenshot Capture

If you want to use screenshot capture on macOS, grant Screen Recording permission to the terminal app that runs the Bridge Server.

Without it, screencapture can return black images.

Path:

System Settings -> Privacy & Security -> Screen Recording

For reliable window capture on an always-on host, it also helps to disable display sleep and auto-lock.

sudo pmset -a displaysleep 0 sleep 0

Development

Repository Layout

ccpocket/
├── packages/bridge/    # Bridge Server (TypeScript, WebSocket)
├── apps/mobile/        # Flutter mobile app
└── package.json        # npm workspaces root

Build From Source

git clone https://github.com/K9i-0/ccpocket.git
cd ccpocket
npm install
cd apps/mobile && flutter pub get && cd ../..

Common Commands

Command	Description
npm run bridge	Start Bridge Server in dev mode
npm run bridge:build	Build the Bridge Server
npm run dev	Restart Bridge and launch the Flutter app
npm run dev -- <device-id>	Same as above, with a specific device
npm run setup	Register the Bridge Server as a launchd service
npm run test:bridge	Run Bridge Server tests
cd apps/mobile && flutter test	Run Flutter tests
cd apps/mobile && dart analyze	Run Dart static analysis

Environment Variables

Variable	Default	Description
BRIDGE_PORT	8765	WebSocket port
BRIDGE_HOST	0.0.0.0	Bind address
BRIDGE_API_KEY	unset	Enables API key authentication
BRIDGE_ALLOWED_DIRS	$HOME	Allowed project directories, comma-separated
DIFF_IMAGE_AUTO_DISPLAY_KB	1024	Auto-display threshold for image diffs
DIFF_IMAGE_MAX_SIZE_MB	5	Max image size for diff previews

License

MIT