@kkcode-app/agent

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

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 |

iPhone notifications

In KKCode, enable notifications and copy the generated command. It includes a phone-owned notification token, saves it to ~/.config/kkcode/notify.json, and registers @kkcode-app/agent in ~/.config/opencode/opencode.json in one step. Restart OpenCode afterwards. Resetting the token in the app immediately invalidates every earlier command. | --status | Show whether the LaunchAgent is installed/loaded/running | off |

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.