CC Pocket

CC Pocket lets you monitor and control Claude Code and Codex running on your Mac from your phone. Check progress, answer questions, approve tools, and review diffs from anywhere.

日本語版 README

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

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

What CC Pocket Can and Can't Do

To set expectations clearly:

If you start a session on your Mac outside CC Pocket, you can resume it later from saved history, but CC Pocket does not take over that live session in progress.

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

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.

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

Project Configuration (.ccpocket.toml)

You can place a .ccpocket.toml file in your project root to configure how the Bridge Server handles worktrees and sandbox settings for that project.

A global ~/.ccpocket.toml is also supported for user-wide defaults. Project-level settings take priority over global ones.

Worktree

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.

The [worktree] section configures file copying and lifecycle hooks:

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.

Sandbox (Claude Code)

The [sandbox] section configures Claude Code's OS-level sandbox behavior when sandbox mode is enabled from the app.

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

# Environment-specific config
# include = ["apps/mobile/android/local.properties"]

# Speed up worktree setup by copying node_modules
includeDirs = ["node_modules"]

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

[sandbox]
autoAllowBash = true

[sandbox.network]
# Allow the dev server to bind to local ports
allowLocalBinding = true

.gtrconfig Compatibility

If your project already uses a .gtrconfig file from git-worktree-runner, the Bridge Server will still read it for worktree settings. When both files exist, .ccpocket.toml takes priority.

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

Environment Variables

License

MIT