cligent

Unified TypeScript SDK for AI coding agent CLIs (Claude Code, Codex CLI, Gemini CLI, Kimi Code, OpenCode, and more).

Register an adapter, send a prompt, and consume a single async event stream — regardless of which agent runs underneath.

Install

npm install @sublang/cligent

The agent SDKs are optional peer dependencies — add the one(s) for the adapters you use:

# `>=` keeps the declaration open so a cligent upgrade can carry the runtime
# forward. A bare `npm install <pkg>` writes a caret instead, and for a
# `0.MINOR.PATCH` package a caret pins the minor: `^0.139.0` never reaches
# `0.146.0`, however often you run `npm update`.
npm install "@anthropic-ai/claude-agent-sdk@>=0.3.219"   # Claude Code
npm install "@openai/codex-sdk@>=0.144.0"                # Codex
npm install "@opencode-ai/sdk@>=1.18.12"                 # OpenCode
# Gemini needs no SDK — the adapter drives the installed `gemini` CLI
# Kimi needs its CLI — see the separately pinned install below

cligent owns which versions of those runtimes work. It refuses one it does not support, naming the version it found, the version it needs, and the command that repairs it — before an agent call rather than in the middle of one. @sublang/cligent/runtime-targets publishes the supported and tested version of every runtime, so a tool built on cligent inherits the policy by upgrading cligent and carries no agent-SDK version knowledge of its own. Note pnpm rewrites >= back into a caret on pnpm update; there, move the pin deliberately and let the lockfile hold it.

The Kimi adapter targets the maintained Kimi Code CLI through ACP. Install the exact conformance target. The external Kimi CLI itself requires Node.js 22.19 or newer to install and run, then authenticate once:

npm install -g @moonshot-ai/kimi-code@0.31.1
kimi login

Adapters reuse each vendor's own authentication from your environment — a signed-in CLI (e.g. claude, codex) or its API-key variable (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY). Kimi Code 0.31 ACP accepts any of three: the OAuth credential created by kimi login, a configured default model whose provider holds non-OAuth credentials, or KIMI_MODEL_NAME plus KIMI_MODEL_API_KEY. A bare MOONSHOT_API_KEY is not one of them, because it names no default model. Cligent stores no credentials and never starts an authentication flow itself.

Runtime and declaration requirements:

• Node.js 18.3.0 or newer for Cligent itself; using the Kimi adapter also requires the external Kimi CLI to run under Node.js 22.19 or newer.
• TypeScript 5.4 or newer when consuming the package declarations.

Quick start

import { Cligent } from '@sublang/cligent';
import { ClaudeCodeAdapter } from '@sublang/cligent/adapters/claude-code';

// Cligent wraps an adapter with role identity, session continuity,
// option merging, and protocol hardening.
const agent = new Cligent(new ClaudeCodeAdapter(), {
  role: 'coder',
  model: 'claude-opus-4-8',
});

for await (const event of agent.run('Refactor auth module')) {
  if (event.type === 'text_delta') process.stdout.write(event.payload.delta);
  if (event.type === 'done') console.log('\nDone:', event.payload.status);
}

// Session continuity — the next run auto-resumes the previous session.
for await (const event of agent.run('Now add tests for it')) {
  // ...
}

Supported agents

• Claude Code — via @anthropic-ai/claude-agent-sdk
• Codex CLI — via @openai/codex-sdk
• Gemini CLI — via child-process NDJSON
• Kimi Code — via one short-lived kimi acp process per run
• OpenCode — via @opencode-ai/sdk

tmux-play

tmux-play is a reference application built on Cligent — a working showcase of what you can compose with the SDK. You chat with a Captain on the left pane; the Captain dispatches work to players, each a Cligent on its own adapter and model, streaming live into its own pane on the right.

npm install -g @sublang/cligent
npm install -g @openai/codex-sdk         # plus at least one agent runtime
tmux-play                                # discover or create config
tmux-play --config ./tmux-play.config.yaml

tmux-play needs at least one agent runtime installed alongside it. The agent SDKs are optional peers, so a global cligent install needs them globally too — that is the same tree its adapters resolve from. Install whichever providers you have credentials for:

Adapter	Install
claude	npm install -g @anthropic-ai/claude-agent-sdk
codex	npm install -g @openai/codex-sdk
gemini	npm install -g @google/gemini-cli
kimi	npm install -g @moonshot-ai/kimi-code@0.31.1 then kimi login (or configure a default model)
opencode	npm install -g @opencode-ai/sdk opencode-ai

On first run, if neither the cwd nor the home config exists, tmux-play creates ${XDG_CONFIG_HOME:-~/.config}/tmux-play/config.yaml wired to the built-in fanout Captain plus one player per installed adapter, taking up to two in the order above — so with the Claude and Codex SDKs installed you get a claude and a codex player. The file is yours to edit afterwards.

tmux-play installs nothing itself. With no agent runtime installed it writes no config and prints an install command for each adapter above; if a configured adapter's runtime is missing, the launcher names it and its install command before starting tmux, rather than failing on your first prompt.

The commands above assume cligent sits where npm installs globally by default. It is the launcher's printed command that is authoritative: an SDK has to land in the one tree cligent resolves from, and a bare npm install [-g] follows whatever prefix or enclosing project your shell's npm happens to resolve, so the launcher prints every SDK command with --prefix already filled in. Run what it prints. The error also names the tree itself, so a layout no canned command reaches stays fixable by hand.

Requirements:

• tmux.
• glow — Markdown renderer used by the in-pane output pipeline; the launcher fails fast if it is missing.
• An installed runtime, plus credentials, for each adapter your config uses: Claude Code, Codex CLI, Gemini CLI, Kimi Code, OpenCode. The launcher checks that the runtime is installed; credentials stay each vendor's own concern and surface when a turn runs.

The Captain is the extension point. tmux-play owns player orchestration, panes, and event streaming; you write a Captain to decide how players collaborate — fanout, planner/router, debate protocol, an XState graph, anything. The built-in fanout Captain runs every player in parallel and synthesizes their answers; swap it for your own using the same contract.

See docs/tmux-play.md for config, layout, notifications, and writing a Captain.

Documentation

• docs/guide.md — Cligent class, adapters, permissions, session continuity, token usage, parallel execution, event types.
• docs/tmux-play.md — tmux-play config, layout, notifications, snapshot, and writing custom Captains.

Contributing

We welcome contributions of all kinds. If you'd like to help:

• 🌟 Star our repo if you find cligent useful.
• Open an issue for bugs or feature requests.
• Open a PR for fixes or improvements.
• Discuss on Discord for support or new ideas.

Live Kimi acceptance automatically discovers a local ~/.kimi-code login and its managed bin/kimi when no override is set. CI reconstructs a dedicated, disposable Kimi source home from the base64 repository secrets KIMI_CODE_CONFIG_TOML_B64 (config.toml) and KIMI_CODE_CREDENTIALS_JSON_B64 (credentials/kimi-code.json). The harness copies those files into an owner-only temporary home and never runs against the source directly. If a cloned run rotates the OAuth refresh credential, repeat kimi login for an affected local source. For the dedicated CI account, repeat the login and replace both repository secrets.

License

Apache-2.0