Kumo CLI

where your code drifts between devices, softly.

Kumo CLI is the desktop companion for the Kumo app. It pairs your terminal with the mobile/desktop client over a secure WebSocket bridge so you can drive Claude Code (and any PTY session) from anywhere — without giving up the comfort of your local shell.

✨ Features

• 🔗 One-tap pairing — link the CLI to your Kumo account with a 9-digit code from the app.
• 🖥️ Real PTY streaming — spawns Claude Code (or any process) via node-pty and mirrors the terminal byte-for-byte.
• 📡 Bi-directional bridge — keystrokes from the app flow back into the local PTY in real time.
• 🪝 Session hooks — auto-injects Claude Code session hooks so your remote views stay in sync.
• 🧠 Smart snapshots — periodic ANSI snapshots keep newly connected viewers up to date instantly.
• 🌐 Bonjour discovery — optional local discovery for zero-config LAN setups.
• 🔒 Local credentials — device tokens are stored under your user config dir, never echoed.

🚀 Quick start

# run on demand (no install)
npx kumo-cli@latest

# or install globally
npm install -g kumo-cli
kumo

On first launch you'll see a prompt:

✦ pairing code › ___

Open the Kumo app, sign in, tap "generate" on the pairing tab, and type the 9 digits back. That's it — your CLI is paired and a session is live.

📦 Requirements

• Node.js ≥ 18 (LTS recommended)
• A working C/C++ toolchain for node-pty:
  • Windows: Visual Studio Build Tools + Python 3
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential, python3, make, gcc
• Claude Code CLI installed and on PATH (only if you plan to use the Claude session features)

🛠️ Configuration

Kumo CLI is configured via environment variables. They can be exported in your shell or placed in a .env file in the working directory.

| Variable | Default | Description | | --- | --- | --- | | KUMO_SERVER_URL | https://kumocli.com/ | Base URL of the Kumo backend. Auto-derives HTTP & WS endpoints. | | KUMO_SERVER_HTTP_URL | derived | Override the HTTP endpoint explicitly. | | KUMO_SERVER_WS_URL | derived | Override the WebSocket endpoint explicitly. | | KUMO_PORT | 3579 | Local port hint (used by some discovery flows). |

Credentials are persisted to your OS config dir (e.g. %APPDATA%\kumo\credentials.json on Windows, ~/.config/kumo/credentials.json on Linux/macOS).

🧭 Usage

kumo                  # interactive: pair if needed, then start a session
kumo --help           # show available flags (if applicable)

To unpair, simply delete the credentials file printed on first pairing, or run:

node -e "require('node:fs').rmSync(require('node:path').join(require('node:os').homedir(), '.config', 'kumo', 'credentials.json'))"

🧱 How it works

┌─────────────┐    WebSocket     ┌──────────────┐     PTY     ┌─────────────┐
│  Kumo app   │  ◄────────────►  │  Kumo CLI    │  ◄───────►  │ Claude Code │
└─────────────┘                  └──────────────┘             └─────────────┘
       ▲                                │
       │       HTTP (pairing)           │
       └────────────────────────────────┘
              Kumo backend

1. The CLI pairs with the backend using the 9-digit code → receives a long-lived deviceToken.
2. It opens a WebSocket to the backend and announces itself.
3. When the app requests a session, the CLI spawns Claude Code under a real PTY.
4. STDIN/STDOUT are streamed both ways; periodic snapshots and Claude session hooks keep state coherent.

🐞 Troubleshooting

• node-pty build fails — make sure your toolchain (above) is installed, then re-run npm install -g kumo-cli.
• Pairing code rejected — codes are single-use and expire quickly. Generate a fresh one in the app.
• Cannot connect — verify KUMO_SERVER_URL matches the backend the app is talking to.
• Hooks not firing — make sure Claude Code is on PATH and you launched a session through the CLI (the hook settings file is auto-generated under the system temp dir).

🤝 Contributing

Issues and PRs are welcome at github.com/kumo-app/kumo.

git clone https://github.com/kumo-app/kumo.git
cd kumo/cli
npm install
npm run dev

📄 License

MIT © Kumo