@gleapai/kai-bridge

中文文档
0.16.1发布于 2026/11/09MITES Module近 30 天下载 3231

Kai Code Bridge runs Kai Code on your computer or server with your own coding subscriptions and local previews.

原始使用文档
文档目录6 节
  1. Accounts
  2. Local dry run
  3. Development
  4. Trying CLI changes locally
  5. Releasing
  6. Computers and your own servers

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"; so do a failed turn and Gleap's STOP (a teammate took the ticket over, replied or stopped the session), neither of which opens a pull request. Claude Code sessions load only the MCP servers Kai passes, not your global ones (KAI_BRIDGE_USER_MCP=1 in the service environment keeps yours). 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).

版本与发布记录

@gleapai/kai-bridge 共发布 40 个版本,首次发布于 2026/08/26;过去 12 个月发布了 40 个版本。

版本发布日期距今
0.16.1latest2026/11/097 天前
0.16.02026/11/097 天前
0.15.12026/10/1829 天前
0.15.02026/10/1829 天前
0.13.02026/10/151 个月前
0.12.152026/10/081 个月前

关于 @gleapai/kai-bridge 的常见问题

@gleapai/kai-bridge 是什么?

Kai Code Bridge runs Kai Code on your computer or server with your own coding subscriptions and local previews.

如何安装 @gleapai/kai-bridge?

在项目目录运行 npm install @gleapai/kai-bridge,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 kai-bridge,可以用 npx kai-bridge 直接运行。

@gleapai/kai-bridge 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gleapai__kai-bridge 是否存在。

@gleapai/kai-bridge 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gleapai/kai-bridge 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gleapai/kai-bridge 可以商用吗?

@gleapai/kai-bridge 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gleapai/kai-bridge 的下载量有多少?

根据 npm 官方下载统计,@gleapai/kai-bridge 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,231 次,日均约 108 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gleapai/kai-bridge 还在维护吗?

最新版本 0.16.1 发布于 2026/11/09(7 天前);至今共发布 40 个版本,其中过去 12 个月发布了 40 个;首次发布于 2026/08/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。