@kkcode-app/agent

高级用户兼容入口。普通用户应安装 KKCode Desktop，由 Desktop 托管 OpenCode、自启、升级、隧道和通知；CLI 继续服务 Linux/headless、已有自动化和调试场景，不再作为新手 onboarding 主路径。

KKCode 的桌面配套工具：它可将电脑上的 OpenCode HTTP server 通过中继连接到手机，并作为 OpenCode 插件向 iPhone 发送提醒。

Install

cd cli
npm install

Usage

Default: spawn opencode serve for you

npx -y @kkcode-app/agent@latest

This will:

1. Spawn opencode serve on 127.0.0.1:<random-port>.
2. Open a WebSocket tunnel to the relay.
3. Print a QR code. In KKCode, open Servers → Scan tunnel QR code, then scan the terminal QR code.

Keep the terminal open while using the connection. The CLI reconnects after a temporary network loss. Use KKCode's manual server-address entry only for a normal LAN/Tailscale/OpenCode URL: a tunnel QR code contains a temporary access token and must be scanned.

Background service (macOS & Linux)

First run the tunnel in the foreground and scan its QR code in KKCode. Then install the tunnel as a background service so it auto-starts on login and auto-restarts on crash. On macOS it uses launchd (LaunchAgent), on Linux it uses a systemd user service. The CLI refuses a first-time --install, because the QR code would only be written to the service log instead of your terminal.

npx -y @kkcode-app/agent@latest --install

The first time you run --install it captures the current PATH and the absolute paths of node and opencode, so the background service can find them even though the service manager does not source your shell profile.

Other commands:

npx -y @kkcode-app/agent@latest --status     # check if installed/loaded/running
npx -y @kkcode-app/agent@latest --restart    # restart the background service
npx -y @kkcode-app/agent@latest --uninstall  # stop and remove the service
npx -y @kkcode-app/agent@latest --version    # print the exact package version npx resolved

The QR payload includes a cli field with the package version, so you can tell which CLI build produced a pairing code. Note the legacy package name @kkcode-app/opencode still resolves to an old release that prints QR v4; always use @kkcode-app/agent@latest.

Logs are written to ~/.config/kkcode/tunnel/tunnel.log. The tunnel code and shared secret are persisted across restarts, so your phone stays connected without re-scanning as long as the relay session hasn't expired. If a legacy ~/.config/opencode-tunnel/config.json exists, it is migrated automatically on first run.

Windows

The foreground flow (npx -y @kkcode-app/agent@latest) works on Windows out of the box — the CLI uses where and shell:true to resolve opencode.cmd installed via npm install -g opencode-ai. If opencode -v works in your shell but the CLI still can't find it, run npm config get prefix and make sure that directory is on your PATH, or pass --command with the absolute path to opencode.cmd.

Background service flags (--install / --uninstall / --stop / --restart / --status) are not supported on Windows yet. Run the CLI inside WSL for the full background-service experience, or keep the foreground process open on Windows.

Attach to an already running opencode serve

opencode serve --port 4096 &
npx -y @kkcode-app/agent@latest --attach --port 4096

Flags

| Flag | Description | Default | | ------------------ | --------------------------------------------------------------------- | ------------------------------------------------- | | --backend <name> | Local backend: opencode | opencode | | --relay <url> | Relay base URL (ws:// or wss://) | $OPENCODE_RELAY_URL or wss://relay.kkcode.app | | --port <n> | Port for opencode serve (random free port if omitted) | random | | --hostname <h> | Local hostname for opencode serve | 127.0.0.1 | | --attach | Don't spawn — reuse an existing opencode serve | off | | --command <bin> | Binary to spawn | $OPENCODE_CMD/opencode | | --reset-tunnel | Forget the saved secret and create a new tunnel | off | | --install | Install as macOS LaunchAgent (background, auto-start on login) | off | | --uninstall | Remove the LaunchAgent and stop the background service | off | | --restart | Restart the background service (kickstart -k / systemctl restart) | off | | --status | Show whether the background service is installed/loaded/running | off | | --update | Upgrade the background service to the latest npm version | off | | -v, --version | Print the CLI package version and exit | off |

iPhone notifications

Pair the phone from KKCode's notification settings or scan the Agent QR code. The CLI stores the stable Agent/Service identity in ~/.config/kkcode/agent.json, detects whether the installed runtime is OpenCode 1 or 2, and incrementally registers the matching plugin entry in the global opencode.json(c). Existing JSONC comments and unrelated plugins are preserved. Restart OpenCode after first-time registration.

The npm package exposes one shared entrypoint ("", ./plugin and ./server all resolve to the same file). Its default export carries both shapes: OpenCode 1 loads server(), OpenCode 2 loads setup. Both map runtime events to the same five KKCode notification types, so the phone and Go notification service do not need version-specific configuration.

How it works

• The CLI registers as a "host" on the relay over a single WebSocket.
• The CLI generates a random shared secret and derives an opaque tunnel ID with SHA-256.
• The phone hits https://relay.example.com/t/<tunnel-id>/... with the secret in a header. The relay forwards each request frame-by-frame over the WebSocket to the CLI, which then fetch()es the local opencode serve and streams the response back.
• Streaming endpoints (SSE) pass through unchanged — chunks are forwarded as they arrive.

The secret is persisted in ~/.config/kkcode/tunnel/config.json so that restarting or reconnecting the CLI gets you the same tunnel without a second scan.

License

MIT.