CCLink Agent

Remote coding agent that bridges local AI coding runtimes with the CCLink mobile app via instant messaging. Claude Code is the default production runtime; Codex is optional when preflight succeeds.

The Agent source is available under the MIT License. Each npm release should match a Git tag with the same version so users can inspect the exact code they install.

Prerequisites

• Node.js >= 16
• Claude Code installed and authenticated (claude --version)
• macOS, Linux, Windows with WSL 2, or native Windows limited mode

Native Windows is a limited Agent mode. It supports chatcc doctor, chatcc pair, chatcc start, native Claude Code CLI, file tree/read/search browsing, and basic chat sessions. It does not support file upload/download, terminal commands, Codex or other runtime selection, or full sandbox parity.

Runtime Rule

CCLink never uses claude -p / print mode. The default Claude Code production path is Claude Agent SDK when available. The CLI stream-json bridge is retained only for GLM compatibility, diagnostics, fixture replay, and emergency fallback; when it is used, prompts must be sent through stdin with --input-format stream-json.

Runtime tool permission and sandbox enforcement belong to each concrete Runtime. The shipped iOS App remains compatible: it keeps the existing permission preferences and Boolean allow-once/reject-once response. Agent may map a preference to an explicitly supported Runtime-native mode, but must not parse a command or decide an individual Runtime tool call. See docs/tool-permission-contract.md and docs/agent-runtime-permission-boundary-minimal-plan.md.

Install

npm install -g chatcc-agent

Persistent interactive Terminal support is optional and independently owned. Install the supported node-pty version into the same stable npm prefix as the global Agent package:

npm install -g --prefix "$(npm config get prefix)" [email protected]
chatcc doctor pty
chatcc restart

Agent only discovers, loads, and performs a real bounded probe of that external package. Installing or upgrading chatcc-agent does not install, rebuild, delete, back up, or restore node-pty. The diagnostic is read-only and reports the expected path plus a precise missing, version, native-load/ABI, helper, or spawn failure reason. Native compilation prerequisites remain a user-managed machine concern; Agent never installs compilers or privileged system packages. A legacy copy under chatcc-agent/node_modules/node-pty is not an independent installation and is deliberately ignored. Install the sibling package with the command above before the first Agent upgrade to this ownership model if PTY must remain continuously available.

On Linux, node-pty may need to compile locally when no matching prebuild is published. Python 3.12 requires node-gyp 10 or newer. Some distro-packaged npm versions still invoke their bundled older node-gyp during dependency lifecycle scripts even when a newer global executable is on PATH. If the install log shows that mismatch, use the following explicit, independently managed build instead of changing the Agent package:

CHATCC_NPM_PREFIX="$(npm config get prefix)"

npm install -g --prefix "$CHATCC_NPM_PREFIX" [email protected]
npm install -g --prefix "$CHATCC_NPM_PREFIX" --ignore-scripts [email protected]

cd "$CHATCC_NPM_PREFIX/lib/node_modules/node-pty"
"$(command -v node)" \
  "$CHATCC_NPM_PREFIX/lib/node_modules/node-gyp/bin/node-gyp.js" \
  rebuild \
  --python=/absolute/path/to/python3 \
  --nodedir=/usr/include/nodejs

chatcc doctor pty
chatcc restart

The --nodedir=/usr/include/nodejs example is for Debian/Ubuntu systems with that header tree installed; use the actual Node header directory on other systems. This procedure installs and builds only the independent global node-pty. Agent install and upgrade code must not perform it automatically.

Usage

Pair and start

chatcc pair
chatcc start

chatcc pair prompts for a Setup Code. Get it from the CCLink app:

1. Open CCLink app → Servers → "Add Server"
2. Copy the complete Setup Code (format: CC-XXXXXXXXXXXXXXXX@tcb_env)
3. Paste it into the terminal

After validation, credentials are saved locally. chatcc start only starts the Agent process. Use the same chatcc pair command to pair additional App clients with this Agent. To unpair, delete the server in the CCLink app. The app updates cloud state, and the running Agent syncs its local allowlist from cloud shortly after. chatcc unpair is kept as an advanced recovery command for administrators.

Commands

chatcc pair        # Pair this Agent with an App Setup Code
chatcc --version   # Print installed Agent version
chatcc start       # Start the daemon (does not pair)
chatcc status      # Lightweight health summary, no model/API call
chatcc ping        # Check cloud reachability with local Agent credentials
chatcc stop        # Stop the daemon
chatcc restart     # Restart the daemon
chatcc sessions    # Inspect local Agent sessions and workspace/client health
chatcc runtimes    # Inspect every built-in runtime's discovery, preflight, and capabilities
chatcc env         # Inspect shell vs daemon environment without leaking secrets
chatcc logs        # Tail local Agent logs
chatcc logs --grep ChatTrace --tail 200 # Filter recent local logs
chatcc support-bundle # Create a local redacted diagnostics bundle
chatcc doctor      # Deep all-in-one diagnostic; may call local runtimes/model APIs
chatcc doctor all --skip-runtime # Deep local diagnostic without model calls
chatcc doctor claude "hello"  # Test the Agent -> Claude Code path
chatcc doctor codex "hello"   # Test Codex runtime discovery and JSONL path (macOS/Linux only)
chatcc doctor codex --runtime codex_cli_sandbox --cwd ~/project "请运行 pwd"
chatcc doctor codex --runtime codex_cli_direct --cwd ~/project "请运行 pwd"
chatcc doctor pty             # Read-only external node-pty path/load/spawn diagnostic
chatcc skill list             # List installed global Skills
chatcc skill install grill-me # Install the built-in grill-me Skill
chatcc skill doctor grill-me  # Check installed Skill metadata
chatcc unpair      # Advanced fallback: unpair a client from the server side
chatcc service install   # Register as systemd service (Linux)
chatcc service status    # Check systemd service status (Linux)
chatcc service uninstall # Remove systemd service (Linux)
chatcc reset --dry-run # Preview local Agent identity/session files to delete
chatcc reset --yes     # Clear local Agent identity and pairing state

Agent 0.8.33 provides an ACP V1 Beta catalog for Kimi Code, Qwen Code, CodeBuddy Code, Gemini CLI, OpenCode, Cursor Agent, GitHub Copilot, goose, Mistral Vibe, Qoder CLI, and DeepAgents. ACP requires Node.js 18 or newer plus an existing local installation and login for the selected runtime. Users or administrators own runtime installation, authentication, and upgrades; ChatCC only discovers, preflights, and starts the concrete runtime on demand. chatcc runtimes --json performs a bounded binary/version plus ACP startup/session preflight without sending a model prompt. Only concrete runtimes whose local preflight passes are advertised to the App; there is no selectable generic ACP runtime. These catalog entries are descriptor-only integrations and all reuse the same AcpBridge; catalog presence is not a claim that every runtime has completed ChatCC real-device certification.

For explicit user Stop, 0.8.33 acknowledges the exact target turn, keeps cancellation idempotent, and escalates from ACP cancel to process termination when necessary. It does not report cancelled or discard the controller until direct child-process exit is confirmed; an unconfirmed exit remains retryable. Android App/IM/Kimi end-to-end acceptance is tracked separately from this Agent repository guarantee.

Each ACP runtime owns its permission behavior. Only when it sends session/request_permission does the Agent forward the complete original request and option set to the App. The App returns one original option ID, and the Agent writes that exact option back without reducing the choices or making a policy decision. A runtime action that proceeds without a permission request is not an App approval. ACP images and compact remain disabled unless separately advertised and verified. Restart recovery is attempted only when the live ACP V1 handshake advertises loadSession; unsupported or failed recovery returns an explicit error and never creates a new context or replays a prompt silently.

Pairing uses the App-generated Setup Code directly and does not run an automatic Agent identity-replacement transaction. If the identity-bound Seq state is missing or corrupt, the Agent fails closed with AGENT_IDENTITY_REPAIR_REQUIRED. Delete the old server in the App, explicitly run chatcc reset --yes, and pair again. Package uninstall and upgrade never delete ~/.chatcc automatically.

Remove or uninstall

For normal unpairing, delete the server in the CCLink app first. This updates cloud pairing state for the current App.

Stop the Agent process:

chatcc stop

Clear local Agent identity for re-pairing:

chatcc reset --dry-run
chatcc reset --yes

Uninstall the npm package:

npm uninstall -g chatcc-agent

If you installed the Linux systemd service, remove the service before removing the npm package:

sudo chatcc service uninstall
npm uninstall -g chatcc-agent

Configuration

Runtime files are stored in ~/.chatcc/:

| File | Description | |------|-------------| | credentials.json | IM credentials (30-day, auto-renewed) | | paired-clients.json | Paired client list | | agent.pid | Daemon process ID | | agent-YYYY-MM-DD.log | Daemon log output | | support-bundles/ | Explicitly generated redacted diagnostics bundles |

Support bundle

For offline troubleshooting, generate a local diagnostics bundle:

chatcc support-bundle
chatcc support-bundle --tail 2000
chatcc support-bundle --output /tmp/chatcc-support --no-archive

The bundle includes status, sessions, runtime discovery, environment summaries, and recent redacted Agent logs. It does not include raw ~/.chatcc/credentials.json. Review the bundle before sharing because paths and recent redacted logs may still reveal project context.

Credentials are obtained via Setup Code and auto-renewed before expiry.

Development

npm install
npm test
npm pack --dry-run

See CONTRIBUTING.md before submitting a change. Report security issues privately as described in SECURITY.md.

How It Works

CCLink App  <-->  Tencent IM  <-->  CCLink Agent  <-->  selected concrete runtime

The agent runs on your server, receives messages from the CCLink app via Tencent IM, and forwards them to the selected local runtime. Claude Code is the default production runtime. Codex and built-in ACP V1 Beta runtimes are advertised only when their local preflight succeeds; the Agent can discover Codex Desktop's bundled CLI even when codex is not in the shell PATH.

Codex runtime variants

Codex is selected per App session, not as a global server mode.

Available Codex variants are reported by chatcc runtimes:

| Runtime | Meaning | |---|---| | codex_cli_sandbox | Uses Codex CLI with --sandbox read-only. This is safer, but on some Linux/Ubuntu hosts the sandbox backend can fail before commands run. | | codex_cli_direct | Uses Codex CLI with --sandbox danger-full-access. This is a trusted-host mode: Codex runs with the Agent user's permissions in the selected project directory. | | codex_desktop | Detected Codex.app bundled runtime. First-class desktop integration is not guaranteed by the Agent. |

Use doctor to verify the exact runtime/cwd/sandbox path before relying on a server:

chatcc runtimes
chatcc doctor codex --runtime codex_cli_sandbox --cwd "$HOME/project" "请运行 pwd 和 ls -la"
chatcc doctor codex --runtime codex_cli_direct --cwd "$HOME/project" "请运行 pwd 和 ls -la"

If codex_cli_sandbox fails with a Linux sandbox or bwrap error but codex_cli_direct succeeds, create the App session with Codex CLI - Direct only for that trusted host/project. Do not treat Direct mode as a security sandbox.

License

MIT