English | 简体中文
Use Claude Code on your laptop without installing or logging into it there.
cc-remote runs Claude Code on a server you can reach over ssh, and runs every tool it calls on your own machine. The model, your login and your subscription stay on the server. Your code, your shell, your toolchain and your editor stay with you.
It's an ACP agent, so it plugs straight into acpc in the terminal, Zed, paseo and any other ACP client. To your editor it looks exactly like Claude Code.
your machine server
┌───────────────────────────────┐ ssh ┌─────────────────────────┐
│ Zed / paseo / any ACP client │ │ claude (logged in) │
│ ⇅ │ ───────► │ model, prompts, │
│ cc-remote │ ◄─────── │ web search, subagents, │
│ Read · Write · Edit · Bash │ │ skills, its own MCP │
│ Glob · Grep · your MCP │ │ │
└───────────────────────────────┘ └─────────────────────────┘
- Your Claude login lives somewhere else. A dev box, a work server, a machine in a region where Claude is available. Log in once there and use it from every computer you own.
- Your code stays local. Unlike ssh-ing into the server and running
claudethere, the files being edited and the commands being run are the ones on your machine, with your dependencies, your git config and your build tools. - Your local MCP servers come along. The ones your editor passes and the ones in your local Claude Code config run on your machine, OAuth logins included.
- Nothing to set up on the server. No daemon, no port, no agent to install. If
ssh <your-server> claude --versionworks, cc-remote works. - One binary locally, on macOS, Linux and Windows. No
claudeinstall and no Claude login on your machine. - It's real Claude Code. cc-remote is
claude-agent-acp, the ACP adapter
for Claude Code, with one change: the
claudeit starts runs on the server. Sessions, permission prompts, modes, models, forks and diffs all work the way they do in claude-agent-acp.
| Runs on your machine | Runs on the server |
|---|---|
| Read, Write, Edit, NotebookEdit, Bash (PowerShell on Windows), Glob, Grep | The model, the system prompt, the session |
| The MCP servers your ACP client brings, and those in your local Claude Code config | Web search, subagents, skills |
Your CLAUDE.md files, git status, environment |
The server's own settings and MCP servers |
Throughout this README, <your-server> stands for your server: replace it with anything ssh
accepts, such as a hostname, user@host, or a Host alias from ~/.ssh/config.
Before you start, have these two in place:
- ssh to the server works.
ssh <your-server>logs you in without a password prompt (use a key, and put ports, users and jump hosts in~/.ssh/config). claudeon the server is logged in. Claude Code 2.1.248 or later, with a POSIX login shell. Runclaudethere once and log in, or usecc-remote --cli auth loginafter installing.
On your machine you need Bun to build cc-remote. The binary it builds has no dependencies. It runs on macOS, Linux and Windows; on Windows it also needs the OpenSSH client that ships with Windows 10 and later.
git clone https://github.com/AkaraChen/cc-remote && cd cc-remote
bun install
bun run compile # builds the binary for this machine into dist/cc-remote
bun link # puts cc-remote on your PATH, in ~/.bun/binbun run compile picks the build:<os>-<arch> script for the machine you run it on. To build
every platform at once (linux-x64, linux-arm64, darwin-arm64, windows-x64, windows-arm64), run
bun run build; the binaries land in dist/.
Tell it which host to use, then check the connection:
mkdir -p ~/.config/cc-remote && echo <your-server> > ~/.config/cc-remote/host
cc-remote doctorcc-remote looks for the host in this order: --host, then $CC_REMOTE_HOST, then
~/.config/cc-remote/host. The host can be anything ssh accepts. Ports, keys and jump hosts
go in ~/.ssh/config.
If you need a different ssh command, set CC_REMOTE_SSH. It works like rsync's RSYNC_RSH:
export CC_REMOTE_SSH="ssh -p 2222 -i ~/.ssh/id_ed25519"If the server isn't logged in yet, run cc-remote --cli auth login.
Once cc-remote is installed, it works with any client that speaks ACP. Add an agent whose command
is cc-remote --host <your-server> (or just cc-remote, if you wrote the host file above).
acpc, in the terminal. acpc gives any ACP agent the Codex terminal UI. Install it, add cc-remote as an agent, and start a session:
curl -fsSL https://raw.githubusercontent.com/AkaraChen/acpc/main/install.sh | sh
acpc add --slug cc-remote --name "Claude (remote)" cc-remote --host <your-server>
acpc -a cc-remotePass --default to acpc add to make it the agent plain acpc starts. In acpc, /model and
Shift+Tab switch Claude's models and modes, /resume reopens sessions, and /agent can move a
conversation between cc-remote and your other agents.
Zed, in settings.json:
"agent_servers": {
"Claude (remote)": { "command": "cc-remote", "args": ["--host", "<your-server>"] }
}paseo, in ~/.paseo/config.json under agents.providers:
"claude-remote": {
"extends": "acp",
"label": "Claude (remote)",
"command": ["cc-remote", "--host", "<your-server>"]
}For paseo there is also a plugin in paseo-plugin/. Install it instead of editing
the config: it adds a "Claude (remote)" provider and a settings screen for the host, the ssh
command and the executable path (Settings → Plugins → cc-remote). The "Check" button there runs
cc-remote doctor.
paseo plugin install github:AkaraChen/cc-remote:paseo-plugincc-remote [--host <host>] speak ACP on stdio (what your client runs)
cc-remote [--host <host>] doctor check ssh and the remote claude version
cc-remote [--host <host>] --cli <args...> run `claude <args...>` on the server
cc-remote --version | --help
Permissions. Permission requests go to your client, the same as with any ACP agent. Read, Glob
and Grep never ask. "Accept edits" approves Write, Edit and NotebookEdit inside the session's
directory. When a Bash command asks, the approval it offers is for a command prefix (such as
npm test:*) rather than all of Bash. PowerShell commands on Windows work the same way. A command with ;, &, |, redirects, $(…), backticks
or newlines is never approved automatically. Prefix approvals last until cc-remote exits.
Sessions. Each session is mirrored to ~/.claude/projects/ on your machine, in the same place
a local Claude Code would keep it. Your client can list, replay, load and fork sessions from there.
If you resume a session the server has never seen, such as a fork, cc-remote copies it to the
server first. On the server, each local directory gets its own empty working folder at
~/.cc-remote/ws/<your hostname>/<local path>/.
MCP servers. Besides the servers your client passes, cc-remote starts the ones your local
Claude Code would: user servers from ~/.claude.json, the ones added for this directory, and the
project's .mcp.json servers that you have approved (in ~/.claude/settings.json,
.claude/settings.local.json, or by approving them in a local claude). They run on your
machine and reach claude the same way as your client's. When names clash, your client's server
wins over your local config's, and either one wins over a server of the same name on the host.
An http or sse server that needs OAuth offers an authenticate tool until you log in. Calling it
opens the login page in your local browser, takes the redirect on localhost, and then the
server's real tools appear. The tokens are kept in ~/.config/cc-remote/mcp-auth/, separately
from Claude Code's.
ssh. By default all sessions share one connection (ControlMaster, kept open for 10 minutes).
Every connection sends ServerAliveInterval=15 and ServerAliveCountMax=3, so a dead link fails
in about a minute instead of hanging. If an -o with the same name comes earlier in
CC_REMOTE_SSH, that one is used instead. Windows' OpenSSH can't share connections, so there each
session opens its own.
Windows. The shell tool is PowerShell instead of Bash, as in Claude Code on Windows. cc-remote
uses PowerShell 7 (pwsh) when it's on PATH, otherwise Windows PowerShell 5.1. Grep needs
ripgrep (rg) on PATH. On the server, a local directory
like C:\Users\me\app gets the working folder ~/.cc-remote/ws/<your hostname>/C/Users/me/app/.
- Your project's
.claude/directory (commands, skills, agents, settings) is not sent to the server. The server's user-level settings, skills and MCP servers still apply. - File checkpoints and rewind are recorded on the server, so they can't see your local edits.
- Bridged MCP servers from your client expose their tools only, not resources or prompts.
- LSP, Monitor and the worktree tools are turned off.
The Claude Agent SDK talks to claude over its stdin and stdout. claude-agent-acp runs the SDK on
your machine, and cc-remote starts claude through ssh -T, so that same stream crosses the
network.
The built-in file and shell tools are turned off on the server. cc-remote replaces them with
local versions that have the same names and inputs, and claude calls them through the SDK's tool
channel, the same way it calls any in-process MCP tool. Your client's MCP servers use that same
channel. A proxy on the stream renames the tools back to their built-in names, so your client
renders diffs and terminals as usual. It also maps the server's paths to your local ones.
claude-agent-acp is patched in one place (patches/): a hook that rewrites the query() options
for each session. See PLAN.md for the full design.
bun install
bun test
bun src/main.ts --host <your-server> # speaks ACP on stdio
bun run compile # dist/cc-remote, for this machine
bun run build # dist/cc-remote-{linux-x64,linux-arm64,darwin-arm64,windows-x64,windows-arm64}test/e2e/ has a minimal ACP client and a fake ssh, which runs the "remote" side on this machine
under a separate HOME. See the header of test/e2e/client.ts for usage.