Skip to content
Projects

Ike-li/claude-chat-mobile

View on GitHub

Ike-li/claude-chat-mobile has 56 GitHub stars and 6 forks. GitHot measured 0 stars in 24 hours and 0 in 7 days. Last checked 2026-11-21 16:48 UTC. Last push 2026-11-18.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
0
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Self-hosted mobile web chat UI for Claude Code — drive your real local claude CLI from your phone. Same CLAUDE.md, MCP, skills, login; any gateway or API key.

AI

README.en.md

Original

Claude Chat Mobile

The Claude Code on your computer — keep driving it from your phone.
Your own local claude · any gateway or API key works · the control plane stays on your machine

中文 · Website · Live demo · Architecture diagrams
CI Apache 2.0 Node >= 20 Ask DeepWiki

The screenshots below show the Chinese UI. The app ships with an English locale too — switch it in Settings.

Sign-in and new-device approval

Home screen, workspace list and the session drawer

Carrying on with coding from the phone Quota usage and background tasks

Switching to a third-party gateway model in session settings

Workspace file browser and slash commands

Settings and status, device management, notifications and lock-screen push

Service status, security events and the on-phone security check

Why use it

  • It drives the same claude you use on your computer. Your local claude CLI, through the Agent SDK: the same CLAUDE.md, MCP servers, skills, login and permission rules. The goal is that anything you can do in the terminal, you can do from the phone.
  • It works where official Remote Control can't. Relays, third-party gateways, API keys, non-Anthropic models, Bedrock / Vertex, telemetry disabled: however your claude is configured, that is what it uses.
  • Every session is already there. All sessions in your connected folders can be viewed and resumed: ones started in the terminal, last week's, ones you never turned remote access on for.
  • The control plane stays on your machine. Server, transcripts, device trust and audit logs all live on your computer, fully self-contained on a LAN, with no account to sign up for.

What you do in the terminal, and how it works on the phone

Walking away from the desk, the fear isn't losing sight of the output — it's that it stalls on something that needs you and waits all night. So these three first:

In the terminal On the phone
Tool approval (y / n) An approval card: Allow / Deny / Interrupt turn (mirrors Esc). Tick "always allow" and pick this session only, or permanently
It asks you something (AskUserQuestion) Tap the option. Multi-select and a free-form "Other…" are there; "Don't answer" lets it carry on, "Interrupt turn" stops it
Did it finish, or is it stuck? Pushed to your lock screen. Approvals, questions and background-task completions are pushed unconditionally, whether or not you have it open

The rest is about getting work done:

In the terminal On the phone
claude for a new session / --resume to dig through history + in the top bar: pick the folder (add or create one right on the phone, or choose "No folder"), the branch, whether to open it in a fresh worktree. The drawer lists every session by project — subfolders get their own section, worktrees sit under their repository — titles generated for you, searchable, live ones marked "running"
Esc to interrupt Stop button in the composer
/model, permission mode, effort Tap the composer chip; takes effect from the next message. All six permission modes
@ to reference a file Type @ to search the workspace and insert @path (same as the terminal; the CLI attaches the file contents)
/ slash commands Type / for candidates, including the skills you installed, each with its description and argument hint; works in a new workspace before the first message
Seeing what it actually changed Open a tool card to preview the diff; each turn ends with a changed-files summary (± lines)
A quick git diff The "Changes" tab in the workspace panel
Rewind or branch off Type /rewind — two steps, as in the terminal: pick the turn to go back before, then restore the code and conversation, the conversation only, or the code only. Anything that touches the conversation forks a new session from that moment; the original survives. To just branch off, tap Fork under a reply (a reply that has just streamed in gets the button once you reopen the session): it copies the conversation only, leaving files alone
Glancing at the statusline Always-on summary in the composer. Expand for model / branch / ctx usage / 5h and 7d quota usage with reset countdowns / estimated spend, copyable in one tap
Watching background tasks A task banner; stop any single one
That session you left open in the terminal Visible, and you can take the wheel — one driver at a time, and it warns you on takeover

Also: image upload and screenshot paste, event catch-up after a reconnect, PWA install to the home screen, a doctor startup self-check, and an optional macOS desktop console.

How it differs from official Remote Control

If you can use official Remote Control and accept its account and data path, use it — zero deployment, and it is the default recommendation. This project is for people the official path refuses, or whose control plane they cannot accept. The first group typically points the claude CLI at a relay, a third-party model or a non-Anthropic one, which shuts the official door outright; the second needs session records and audit logs to stay on their own machine.

Official Remote Control Claude Chat Mobile
Model path Requires a claude.ai sign-in and a direct connection to api.anthropic.com. API keys, Bedrock / Google Agent Platform / Microsoft Foundry, an ANTHROPIC_BASE_URL pointing elsewhere, telemetry switches like DISABLE_TELEMETRY, ZDR organizations — any one of these rules it out entirely Whatever your claude CLI is configured with — third-party gateway / API key / Bedrock / Vertex / telemetry disabled all work
Control-plane data Session transcripts are stored on Anthropic's servers for cross-device sync Service, transcripts, device trust and audit logs all stay on your machine; fully self-contained on a LAN
What you can see Only sessions you explicitly enabled Remote Control on (or new ones once auto-connect is on); /resume is terminal-only, so you cannot browse session history from a phone Every session in your connected folders — started in a terminal, left over from last week, all visible and resumable
Driving one session from both ends Yes — send from terminal, web or phone interchangeably No — single-driver model; the web side must explicitly take over, and that can fork the session
Deployment cost None You run a server yourself

A note on wording: this is not "data never leaves your machine" — model requests are still sent by the local claude CLI using your existing configuration. What CCM promises is that it adds no additional data egress beyond that.

CCM makes no assumption about where it runs: wherever your claude CLI works, the control plane follows. Your own dev machine is the main case; a remote server works just the same, with your phone connecting to that server.

Three steps to run it

You need Node.js ≥ 20 and a working local claude CLI. This project does not install or sign you into Claude.

curl -fsSL https://github.com/Ike-li/claude-chat-mobile/archive/refs/heads/master.tar.gz | tar xz
cd claude-chat-mobile-master
npm ci --omit=dev && npm run setup && npm start

Open the address printed in the terminal on your phone. The first time a new device connects it needs one approval: node scripts/device.js list, then approve <ID>. Typing a 64-character token on a phone is painful — node scripts/qr.js renders the address as a terminal QR code.

A running server ≠ a working chat. If chat doesn't work from the phone, get claude through one turn in your host terminal first, then retry. Full checklist: Getting Started §8.

To change code or run tests, git clone the full repository instead. Configuration, non-interactive setup, PWA, CLI hooks and how to update: → Getting Started

What it looks like

Try it before installing anything: live demo. It runs this repo's real frontend (app/public/ verbatim) with only the backend swapped for an in-browser script — workspace switching, streaming replies, tool calls, approval cards, file browsing, background tasks and the settings pages are all clickable, but replies are canned and no model is ever called.

How it works

Phone PWA / browser ↕ Socket.io ↕ CCM Server (local) ↕ Claude Agent SDK ↕ local claude CLI

The phone is only a remote control plane. What actually executes code, reads the project, calls tools and maintains sessions is still the Claude Code on your computer — no database, no multi-tenancy, no SaaS backend.

One boundary worth knowing: a live session has exactly one driver at a time. While the terminal is driving, the Web side is read-only by default; you can explicitly resume from the Web, but that may fork the session. The two never type into the same live Claude process at once.

Before leaving the computer, /exit the session in the terminal; when you are back, reopen it with claude -c or claude --resume. A terminal left open does not know what you said on the phone. If it writes anything or exits later, the next resume continues from its branch, and the phone segment is not in the model's context. If that happens, you are asked before sending: fork a new session that keeps the phone segment, or send anyway.

Dual path, event sync, session takeover: → Architecture guide

Remote access

Scenario Method
Same Wi-Fi LAN address — the simplest first run
Temporary public Cloudflare Quick Tunnel, ngrok, other hosted tunnels
Long-term public fixed domain + Cloudflare Tunnel + Access
Off Cloudflare Tailscale (recommended, HTTPS included), other encrypted tunnels / VPNs, self-hosted reverse proxy

The setup wizard asks how your phone will reach this machine; the answer is stored as ACCESS_PROFILE, and doctor plus the on-phone security check tailor themselves to it. The product never installs third-party tunnel tools — it only points to the docs. PWA install and Web Push require HTTPS (on iOS also 16.4+ and installing to the Home Screen first).

→ Deployment and operations (Chinese)

Security Model

This is an entry point that can reach the Claude Code on your machine remotely, and through it indirectly obtain local code execution. Treat it as a remote control tool for a development machine, not as an ordinary web page.

  1. Single user. There is no multi-user or tenant isolation; an authenticated operation carries the permissions of the local account running claude.
  2. No token, no server. AUTH_TOKEN is a startup prerequisite under every bind mode — even a browser on this machine needs it. There is no "local means no auth" path.
  3. Work stays inside connected folders. Files, sessions and related operations can only reach the folders in WORKDIRS, their subfolders, and those repositories' own git worktrees; "No folder" sessions run in a throwaway directory the app creates. Folders can be added from the phone, but not your home folder itself, the disk root, or ~/.claude. The wider you connect, the more your phone can reach: connect something as broad as ~/code and every project inside it is in reach.
  4. New devices need trust. Except for direct connections with a local-looking Host and those already validated by the optional public identity layer (currently Cloudflare Access), a device holding the correct token still needs one approval. Two caveats: when Access is on it replaces device approval, so the trust list does not govern connections arriving through it; and the local check reads the Host header, which the client writes, so under plain TCP forwarding (ssh -R, frp tcp) a remote client can send Host: localhost and pass as local. Set DEVICE_APPROVAL_SCOPE=all to make approval apply to every path.
  5. Claude Code permissions are inherited. Existing rules such as permissions.allow stay in effect; review your automatic Bash / Write approvals before public use.
  6. The file editor is a direct write. It does not pass through the Agent tool-approval chain (it does enforce scope checks, a size limit, content-hash conflict detection and audit logging). Set FILE_EDIT=off to disable it; turning it off is recommended for long-term public exposure.

Read deployment and operations (Chinese) before exposing it publicly for the long term. Report vulnerabilities privately through GitHub Security Advisories, not a public issue.

Docs

Using it

  • Getting Started — from install to your phone's first message; configuration, updating, command reference
  • Deployment and operations (Chinese) — LAN to long-term public entry points, Cloudflare Tunnel / Access, off-Cloudflare alternatives
  • Security policy — how to report a vulnerability privately

Contributing

Config keys and commands are not maintained as static lists: node scripts/config.js schema prints the current definitions, and every CLI prints its own usage when run without a subcommand.

Community and feedback

Bugs and feature requests go to GitHub Issues; security vulnerabilities go to Security Advisories.

⚠️ Never paste your AUTH_TOKEN, public domain, full ccm.config.json or raw doctor output into a public channel — those are enough for someone to take over your machine.

License

Apache-2.0 © 2026 Ike-li. See also NOTICE. You may use, study, modify, self-host and redistribute it, including commercially and in closed-source products. Redistribution is subject to the conditions in Section 4 of the License, which include keeping the copyright notice and NOTICE attribution, including a copy of the License, and marking the files you changed; see LICENSE for the authoritative text. Versions up to and including v1.10.2 were released under AGPL-3.0-only; the change is not retroactive.

Explore related projects

Loading…