Kai Code Bridge

Run Gleap Kai Code on your computer or server with your own Claude Code / Codex login, and local dev-server previews.

npm i -g @gleapai/kai-bridge   # one install, so the background service has a stable path
kai-bridge login             # pair this machine with your Gleap account
kai-bridge service install   # run at login (launchd / systemd / Task Scheduler)
kai-bridge status
kai-bridge ps                # sessions running on this machine, with dashboard links (--json for tooling)

(npx @gleapai/kai-bridge login works for a quick look, but install needs the global install — npm garbage-collects the npx cache, which would leave the background service pointing at a deleted file.)

Then pick Run on → your machine in any Kai Code session. Repos are discovered automatically under ~/Documents, ~/code, ~/dev, ~/Projects, ~/src (add more with kai-bridge repo roots add <dir>); each session runs in an isolated worktree under ~/.kai/worktrees unless you choose "Work in my checkout". A session keeps its coding agent running between turns, so background jobs and dev servers the agent started survive into your next message (idle sessions end after 30 minutes, or 2 hours while background work runs; at most 4 per machine; KAI_BRIDGE_LIVE_SESSIONS=0 starts a fresh agent per turn). Stopping a turn ends that agent and pushes the agent's edits to the session branch as "Kai Code: work in progress", and once a day the worktrees of sessions that ended days ago (merged, stopped, failed, closed) are removed, unless they hold uncommitted changes or unpushed commits.

Accounts

The bridge runs the official claude / codex binaries installed on your machine under your login (ambient profile). Add a second account with a managed profile:

kai-bridge profile add personal --harness claude
kai-bridge profile login personal

Your harness logins never leave the machine; the bridge stores only its pairing token (~/.kai/config.json).

Local dry run

kai-bridge run --task "Explain the auth flow in this repo" --cwd ~/code/my-app

Development

npm run sync-runner [-- <analyzer checkout>] copies the ACP runner from a gleap_code_analyzer checkout (default: the gleap_code_analyzer beside this checkout or one of its parents, so it is found from a .claude/worktrees/* worktree too) and pins it in runner/SOURCE.json (analyzer commit + a sha256 per file). Never edit runner/ by hand: change the analyzer's e2b-coder-template/runner (device-only behaviour goes behind KAI_RUNNER_HOST=device), commit it there, then sync. npm test runs the unit suite (uses real git) including the drift check (npm run check-runner), which fails on a hand-edited or dirty-synced runner.

Trying CLI changes locally

npm run cli -- status          # any kai-bridge command, run from this checkout
npm run cli -- login --name "dev laptop"
npm run cli -- start           # foreground daemon; Ctrl-C stops it
npm run test:cli               # fast CLI regression suite (test/cli.test.mjs)

npm run cli (scripts/dev-cli.mjs) uses <repo>/.kai-dev as KAI_HOME and turns self-update off, so it never touches ~/.kai or the background service running the released version. Export KAI_API_BASE / KAI_APP_BASE to point it at a local server. Don't npm link the package: the login service runs the global install by absolute path, and a link would swap that for this checkout.

Releasing

Merging is releasing. Every merge to main that changes what the package ships (bin, src, runner, the shipped scripts, dependencies) publishes the next patch after npm's latest (0.12.9, 0.12.10, …), tags v<version> and creates a GitHub release (the CHANGELOG.md section if there is one, else the commit list); paired devices pick it up through self-update. Docs/CI-only merges publish nothing. Before publishing, the workflow checks that the runner commit pinned in runner/SOURCE.json is on GleapSDK/gleap_code_analyzer main (node scripts/check-runner.mjs --on-main, GitHub's compare API). That needs the repository secret ANALYZER_READ_TOKEN: a fine-grained token with Contents: read on GleapSDK/gleap_code_analyzer. Without it, or with a runner synced from an unmerged analyzer branch, the release fails — merge the analyzer change, sync from its main, and merge again. package.json on main keeps the last hand-set version — the auto version lives in the tag and on npm.

For a minor or major, bump version in the PR (npm version minor --no-git-tag-version) and add its ## <version> changelog section. A prerelease version (0.13.0-beta.1) goes out under the next tag, which self-update ignores (npm i -g @gleapai/kai-bridge@next to try it). The logic is scripts/next-release.mjs.

Computers and your own servers

Kai Code offers Kai Code Cloud (Gleap's managed execution, using AI credits) or Kai Code Bridge (your coding agents on your computer or a server you manage, using your own AI subscriptions).

Run npm i -g @gleapai/kai-bridge && kai-bridge in a local terminal or over SSH. The guided setup pairs the device, installs its background service and helps sign in to coding agents. Node.js 20+ and Git are required. On a Linux server, keep the user service running after logout using your system's service configuration; kai-bridge service status and kai-bridge service logs --follow show what it is doing.

Codex and Claude Code ship with Kai Code Bridge. Missing agents can be installed or repaired, and existing agents can be updated independently:

kai-bridge harness install codex
kai-bridge harness update codex
kai-bridge profile login codex --device-auth

kai-bridge harness install claude
kai-bridge harness update claude
kai-bridge profile login claude

Updates install into ~/.kai/harnesses, verify the new executable, then select it for subsequent sessions. A failed download or startup leaves the previous version selected. Existing versions are retained for running sessions; your global CLI installations and agent logins are not overwritten. --version <version> selects a specific package version (for Claude, the Claude Agent SDK package version).

Codex automatically uses device-code sign-in over SSH or on headless Linux. Enable device-code sign-in in the account settings if Codex asks. Claude uses its native auth login flow: follow the URL and prompts in the SSH terminal. Dashboard Sign in opens a terminal on desktop devices; for headless servers it shows the exact command to run over SSH. The login is picked up automatically.

Previews boot local to the Kai Code Bridge device. Open them on that computer, or click Make public in the dashboard's Preview popover to get a stable HTTPS link (https://web-<repo>-<id>.gleap-preview.dev) that works from a phone or a teammate's laptop. Public links run through a Cloudflare Tunnel: the daemon starts cloudflared on the device (it uses one from your PATH, else downloads a pinned release into ~/.kai/bin; brew install cloudflared, apt install cloudflared or winget install Cloudflare.cloudflared also work). The address is the same for every ticket of a repo on this device, so a saved login survives from one ticket to the next, and only one ticket per repo can be public on a device at a time: making another one public points the same link at it and stops the previous preview (its owner sees a notice). Nothing leaves the device until someone clicks Make public. kai-bridge ps shows what is running.

A preview starts from the repo's .gleap/dev.yaml, else Claude Code's .claude/launch.json (its first configuration that runs inside the repo), else the package.json dev / start script. Kai can also start a dev server itself during a turn and expose it: it then shows up as the session's preview like one you started. While it works, Kai checks the app in a headless browser (your Chrome, else Playwright's Chromium when it is installed; KAI_BROWSER_MCP=0 in the service environment turns that off).