Forking Guide

Build your own agent workflow on CC Pocket.

CC Pocket is a Flutter app plus a TypeScript Bridge Server for running local Codex and Claude sessions from mobile and desktop clients. This page explains the stack, boundaries, and extension points for forks.

Open Markdown version View source
CC Pocket app Flutter client for iOS, iPadOS, Android, macOS, Linux, and Windows.
JSON WebSocket
Bridge Server Node.js / TypeScript process running on the user's machine.
local tools, shell, git, filesystem
Codex / Claude Agent sessions keep running where the project lives.

Repository Shape

The repository is split around one protocol boundary: app clients talk to a self-hosted Bridge Server, and the Bridge talks to local agent tools and the user's workspace. 

ccpocket/
├── apps/mobile/        Flutter app for mobile and desktop clients
├── packages/bridge/    TypeScript Bridge Server published as @ccpocket/bridge
├── docs/               GitHub Pages site and design notes
├── scripts/            release, development, and asset automation
├── functions/          Firebase Cloud Functions for push relay support
└── package.json        npm workspace root

Bridge Server

The Bridge Server is the part most forks extend when they need new data sources, private APIs, or workflow-specific operations.

RuntimeNode.js 18+, TypeScript, ESM, NodeNext
Networkingws WebSocket server, HTTP endpoints, QR setup, mDNS
Agent integrationClaude Agent SDK and local Codex CLI / app-server transport
Host integrationgit, worktrees, filesystem, screenshots, launchd, systemd, proxy support
Persistencesession indexes, prompt history, image gallery, debug traces, worktree metadata
ValidationVitest unit tests and TypeScript type checks

Flutter App

The app is organized feature-first so forks can add or remove complete workflow surfaces without rewriting the transport layer.

Client stack

  • Flutter and Dart
  • iOS, iPadOS, Android, macOS, Linux, Windows
  • flutter_bloc / Cubit, provider, and hooks
  • auto_route, Freezed, JSON serialization

Device features

  • WebSocket connection to Bridge
  • QR scan, mDNS discovery, deep links, SSH host management
  • Firebase Messaging, RevenueCat supporter flow, Shorebird updates
  • Markdown, code highlighting, image picking, clipboard, drag and drop

Protocol Boundary

Features cross the app/Bridge boundary through explicit JSON messages. This keeps mobile, desktop, and future custom clients compatible with a self-hosted Bridge.

Client to Bridge

  • start, input, approve, reject
  • answer, list_sessions, stop_session
  • get_history, get_diff, git and file operations

Bridge to Client

  • system, assistant, stream_delta
  • permission_request, tool_result, status
  • history, session_list, diff_result, error

What Forks Can Reuse

Workflow UI

Chat sessions, approvals, questions, prompt history, file preview, image viewing, and Git review surfaces.

Bridge Sync

Multi-session state, local history compatibility, reconnect behavior, offline recovery, and host setup.

Private Integrations

Add Jira, Linear, GitHub, or internal REST API panels where GUI workflows are faster than prompts or MCP.

Extension Pattern

A typical fork adds Bridge behavior first, then exposes it through a typed app service and a feature UI. 

1. Add Bridge-side data access or operations in packages/bridge/src/
2. Add protocol types in parser.ts and routing in websocket.ts
3. Add a Flutter service stream or request method in apps/mobile/lib/services/
4. Add feature UI under apps/mobile/lib/features/<feature>/
5. Add focused tests for protocol parsing, Bridge behavior, and Flutter state

Platform Notes

macOS is the primary development environment. Linux and Windows desktop builds are available as experimental targets, and Windows Bridge support is handled on a best-effort basis unless a change is covered by tests and reporter-side validation.