cc-remote README

项目的 README,来自 github.com/AkaraChen/cc-remote。合并为一个 markdown 文件:README.md。

cc-remote

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       │          │                         │
 └───────────────────────────────┘          └─────────────────────────┘

Why

What runs where

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

Requirements

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:

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.

Install

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/bin

bun 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 doctor

cc-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.

Use

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-remote

Pass --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-plugin

Commands

cc-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

Behavior

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/.

Limits

How it works

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.

Develop

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.

cc-remote (AkaraChen/cc-remote)

正在搜索数据库…

这是什么?它在你通过 ssh 连接的远程服务器上运行 Claude Code,使用模型、你的 Claude 登录和订阅;而它调用的每个文件、shell 和构建工具都在你自己的机器上运行。
这是独立的 Claude Code,还是编辑器的插件?它是一个 ACP 智能体(claude-agent-acp 加一处改动),因此可以接入 ACP 客户端,例如终端里的 acpc、Zed 或 paseo。对这些客户端来说,它与 Claude Code 完全一样。
怎样让它跑起来?克隆仓库,然后运行 'bun run compile',为你自己的机器构建可执行文件。接着用 --host、CCREMOTEHOST 环境变量或 ~/.config/cc-remote/host 指向你的服务器,并运行 'cc-remote doctor' 检查连接。
我的机器和服务器上需要准备什么?你的机器需要 Bun 来构建可执行文件,该文件没有依赖。服务器需要 Claude Code 2.1.248 或更高版本,并带有 POSIX 登录 shell,你还必须在那里登录 Claude,而且通过 ssh 连接服务器时不能弹出密码提示。
安装前有哪些限制需要了解?你项目里的 .claude 文件夹不会发送到服务器,因此其中的命令、技能和设置都会被忽略。文件检查点和回退只能看到在服务器上做的修改,LSP、Monitor 以及工作树工具会被关闭。
我的代码和 Claude 登录信息最终去了哪里?模型、你的 Claude 登录和订阅都留在服务器上。你的代码、shell、工具链和编辑器留在你的机器上,工具调用和结果则通过 ssh 在两者之间传递。
我本地的 MCP 服务器还能用吗?可以。编辑器传入的 MCP 服务器,以及你本地 Claude Code 配置中的 MCP 服务器,都在你的机器上运行,包括 OAuth 登录;它们的工具通过与内置工具相同的通道提供给 Claude。
这和直接 ssh 登录服务器再运行 claude 有什么不同?直接 ssh 的话,文件和命令都在服务器上。使用 cc-remote 时,被编辑的文件和执行的命令都在你的机器上,并使用你机器上的依赖、git 配置和构建工具。
服务器上需要安装什么吗?不需要守护进程、端口或代理。只要在服务器上 'ssh claude --version' 能正常运行,cc-remote 也就能用。
有哪些类似的项目?claude-code, free-code, claudecodeui, maki, oh-my-pi, claurst, ovis, zuse
作者
AkaraChen
大小
0.2 MB
星标
407
更新
提交Nov 09
时长
17天
提交 · 90 天