Zhin.js

One codebase. Every chat platform. TypeScript.
Multi-channel · Opt-in AI · Remote Console

Documentation · Wiki · Delivery Board · Live Demo · Remote Console · Contributing

Zhin.js is built for developers and teams shipping serious bots / assistants on chat platforms (DMs, groups, schedules, notifications, AI chat). It is not a Cursor / Claude Code–style coding agent.

Multi-channel — one codebase on 20+ platforms (QQ / WeChat / Discord / Slack / DingTalk / Telegram…); one bot can run many accounts across many platforms
Opt-in AI — default install is a <10MB IM framework; add @zhin.js/agent for a full agent (tools / memory / orchestration / MCP)
Remote Console — manage the bot in the browser: send messages, edit config, read logs, run schedules — no code required

// bot.ts — a whole bot can be this one file
import { defineCommand } from 'zhin.js/command'
import { definePlugin } from 'zhin.js/plugin-runtime'

export default definePlugin({
  name: 'my-bot',
  setup({ addCommand }) {
    addCommand('hello', defineCommand({
      description: 'Say hello',
      execute: () => 'Hello from Zhin!',
    }))
  },
})

Quick Start

Three steps. No adapter boilerplate:

npm create zhin-app my-bot -y
cd my-bot
pnpm dev

Open Remote Console → enter the API Base printed at startup (new projects currently use http://127.0.0.1:8068) → send /hello in Sandbox. Done.

-y takes the IM golden path: Sandbox + Host + Console. No model key required.

Path	Who	Time
demo.zhin.dev	Zero install	Instant
`npm create zhin-app -y`	Standalone project (recommended)	~1 min
`examples/single-file-bot`	“One `bot.ts` is the bot”	Clone, then `pnpm --filter single-file-bot dev`
`examples/minimal-bot`	Contributors / convention-dir template	Root `pnpm dev`

More: Getting started · Examples · npx zhin setup · npx zhin doctor

Requirements: scaffolded TypeScript projects require Node.js ≥22.12.0, pnpm 9+. The compiled IM library supports Node.js ^20.19.0 or >=22.12.0.

The <10MB figure applies to the IM library install. The generated project also installs the CLI, Sandbox adapter, page/layout contracts, and a Satori card example. The browser UI lives at console.zhin.dev; the CLI assembles its HTTP Host and Console API. Neither the browser UI nor an MCP server is bundled into zhin.js.

From a message to durable work

Zhin starts with one normalized message stream. A message can match a command, pass through middleware, enter an Agent turn, call governed capabilities, start durable work, and return through the same send pipeline.

Each layer is optional. The IM core stays small; AI, rich media, speech, Remote Console, and external protocols are installed only when the product needs them.

flowchart LR
    A[Adapters & Endpoints] --> B[Message pipeline]
    B --> C[Commands & Middleware]
    B --> D[Agent turn]
    D --> E[Tools · Skills · MCP]
    E --> F[Sub-agents · Schedules · Workroom]
    C --> G[Reply]
    F --> G
    H[Plugin Runtime · Config · Generations] -. governs .-> B
    H -. governs .-> D
    H -. governs .-> E
    I[Journal · Console · Host APIs] -. observes .-> B
    I -. observes .-> D
    I -. observes .-> F

Capability map

Surface	What it covers	Explore
Connect	20+ adapters, multiple accounts and endpoints, normalized inbound/outbound messages, rich media, STT and TTS	Adapters · Message flow · Speech
Interact	Commands, middleware, components, replies, schedules, notifications, and AI trigger/access rules	Commands · Middleware & components · AI configuration
Extend	Plugin manifests, convention directories, scoped instances, child plugins, Console pages, and reusable npm delivery	Plugin model · Conventions · Plugin delivery
Understand	Model/provider routing, multimodal input, Prompt Sections, conversation history, memory, session trees, and compaction	AI overview · Agent authoring · Agent deep dive
Act	Built-in and plugin Tools, Skills, MCP, deferred discovery, permissions, approval, cancellation, and execution Journal	Tools & Skills · Agent runtime · Capability Seam
Coordinate	Sub-agents, scheduled turns, persistent Workroom runs/tasks, review, sponsor gates, recovery, and A2A hosts	Agent orchestration · Governed Agent · `packages/host`
Evolve safely	Generation-based HMR, candidate validation, atomic publication, owner-scoped configuration, rollback, and endpoint lifecycle	Generation lifecycle · Config as data · Endpoint lifecycle
Operate & deliver	Remote Console, logs and diagnostics, HTTP/MCP/A2A hosts, scaffolding, production templates, harnesses, and changesets	Console · Production · Contributing

Built to stay operable

These surfaces share one Plugin Runtime instead of forming separate execution islands:

Published plugins have a runtime contract — the manifest declares protocol, engine range, Features, child plugins, isolation and instances; one package can be mounted more than once with separate scope and config (plugin model).
Hot reload is a Generation transaction — the next plugin tree is prepared and validated off-path, then published atomically; a failed candidate leaves the active Generation serving traffic (Generation lifecycle).
Configuration is owned data — schemas compose across the plugin tree, each plugin receives its owner projection, and revisioned updates can roll back when activation fails (config as data).
Agent execution has one authority path — Prompt, Tool, Skill and MCP capabilities enter a fixed snapshot; generation checks, permissions, approval, cancellation and journaling stay in the Turn runtime (Agent deep dive).
External providers use the same governance — the Advanced Capability Seam projects Root services through CapabilityIngress; it does not expose a policy-free execute-by-name path.

Stable / Advanced capability tiers

Tier	Feature	Notes
Stable	IM core	Sandbox + commands + Console
Stable	AI (optional)	`@zhin.js/agent` + provider
Stable	Plugins / HMR / TypeScript	Hooks API, full types
Stable	Security (baseline)	Bash allowlist, file policy, approval
Advanced	Multi-endpoint	IM / email / GitHub / webhook…
Advanced	Feature / MCP / toolSearch	Orchestration, deferred workers

Install tiers (zhin.js 1.1.x)

Official packages use the owner-governed 1.1.x stable line. Routine releases are patch-only.

SSOT (Chinese table): docs/snippets/install-tiers.md · site: Install tiers · Chinese README: README.zh-CN.md

Tier	Install	~production size	Capabilities
IM	`pnpm add zhin.js` + an adapter (e.g. `@zhin.js/adapter-sandbox`); dev: `@zhin.js/cli`	<10MB (library)	Plugin Runtime; command / component / adapter convention dirs (Stable Features inherited via `@zhin.js/core` `zhin.features`; Host is optional peer + `zhin.plugins`, see ADR 0053)
AI	`+ @zhin.js/agent zod ai`	+~12–15MB	ZhinAgent, sessions, tools, compaction
Provider	`+ @ai-sdk/openai` etc.	per vendor	LLM calls
MCP	`+ @modelcontextprotocol/sdk`	+ a few MB	MCP client
Rich media	`+ @zhin.js/html-renderer`	+ a few MB	outbound `html` / `markdown` → PNG (falls back to text if missing)
Speech	`+ @zhin.js/speech`	+ a few MB	inbound STT, outbound TTS, `segment.tts` (warn + degrade if missing)

Compatibility note for the 1.1 stable line: import from 'zhin.js' no longer includes ZhinAgent / AIService. Use zhin.js/agent or zhin.js/ai. See ADR 0019.

MCP has two separate roles: ai.mcpServers connects the optional Agent to external servers (client setup); a top-level mcp: block exposes this bot as a server and requires @zhin.js/mcp plus the Agent runtime (server setup). Neither is enabled by the IM library alone.

Windows: Getting started.

Enable AI (optional)

pnpm add @zhin.js/agent zod ai
pnpm add @ai-sdk/openai   # swap as needed

# zhin.config.yml
ai:
  enabled: true
  providers:
    openai-main:
      sdk: openai
      apiKey: ${AI_API_KEY}
  agents:
    zhin:
      provider: openai-main
      model: gpt-4o-mini
  agent:
    execSecurity: allowlist
    execApprovalMode: ask

Deeper: AI · Agent runtime & security · Prompt Sections, tools & skills

Adapters

Platform	Package	Platform	Package
Sandbox (Stable)	`@zhin.js/adapter-sandbox`	QQ / ICQQ	`@zhin.js/adapter-icqq`
QQ official	`@zhin.js/adapter-qq`	NapCat	`@zhin.js/adapter-napcat`
OneBot 11 / 12	`@zhin.js/adapter-onebot11` / `onebot12`	Discord	`@zhin.js/adapter-discord`
Telegram	`@zhin.js/adapter-telegram`	Slack	`@zhin.js/adapter-slack`
KOOK / DingTalk / Lark	`kook` / `dingtalk` / `lark`	GitHub	`@zhin.js/adapter-github`
Email / WeCom / LINE	`email` / `wecom` / `line`	Satori / WeChat MP	`satori` / `wechat-mp`

Full list: adapter docs · plugins/adapters

Package Map

Package	Role
`zhin.js`	IM entry (1.1.x stable line)
`@zhin.js/core`	Plugin / Adapter / Dispatcher
`@zhin.js/ai`	AI engine (no IM)
`@zhin.js/agent`	Agent orchestration & security
`@zhin.js/cli` · `create-zhin-app`	CLI / scaffold

Layers and dependency direction: architecture · repo structure

Documentation


Start	Getting started · Roadmap & boundaries · Stability · Docker · Windows
Basics	Architecture · Config · Commands · Plugins
Advanced	AI · Prompt Sections, Tools & Skills · Agent runtime · Message flow
Develop	Plugin authoring · Contributing · Architecture
Knowledge index	Practical answers · Source archive and corrections

Site: zhin.js.org · Chinese docs: zhin.js.org (switch language in the docs nav)

CLI

pnpm dev                 # this repo defaults to minimal-bot; maintainers: pnpm dev:test
npx zhin new my-plugin   # plugin template
npx zhin setup           # incremental config wizard
npx zhin doctor          # environment diagnostics
npx zhin search <kw>     # search plugins

Contributing

git clone https://github.com/zhinjs/zhin.git
cd zhin
pnpm install && pnpm build
cd examples/minimal-bot && pnpm dev

See Contributing. Root pnpm dev points at the Stable convention-dir template minimal-bot. For “one file is the bot”, use pnpm --filter single-file-bot dev. Kitchen-sink: pnpm dev:test (test-bot) — not a user template.

Repobeats

License

MIT

zhin

Links

README