Choose your path
Zhin serves two kinds of people. Pick yours — the rest of this README is split the same way.
What is Zhin.js?
Zhin.js is a framework for bots that live in chat apps — operators run them from a browser console, developers build them in TypeScript. Think community bots, personal assistants, notification and support bots, AI chat assistants.
- One codebase, many platforms. Adapters translate each platform into one unified message, so your commands and replies work everywhere. One bot can run many accounts on many platforms at once.
- A feature is a file.
commands/hello/index.tsis the/hellocommand. Middleware, message cards, scheduled jobs and AI tools work the same way — no registration boilerplate. - Small by default, AI when you want it. The IM core is under 10MB and needs no model key. Add LLMs, tools, memory and MCP with one command.
- Hot reload that can't take you down. Save a file and the bot reloads. If the new code fails, the previous version keeps serving.
- Managed from the browser. console.zhin.dev lets you send test messages, read logs, edit config and manage plugins — nothing to deploy.
Zhin is not an in-editor coding agent (like Cursor or Claude Code). Its AI features exist to power bots on chat platforms.
For operators and group owners
You don't need to write code to run a Zhin bot well. Once a developer (or your ops person) has deployed it once, day-to-day work happens in the browser.
Connect. Open console.zhin.dev and enter the bot's API address and token (HTTP_TOKEN). Use a read-only Demo token for colleagues who only watch. Not deployed yet? Try the live demo first.
Group ops with guardrails. The AI can draft announcements but only a person with approval rights can send them; risky admin actions such as kicking a member become approval cards with a cooldown; every decision is traceable in decision replay.
When to call a developer: first deployment or server moves, a feature no existing plugin provides, a new platform, connecting the AI to your business systems, or errors in the run log you can't interpret.
👉 Full guide: Operator & Group Admin Guide · Console path · Troubleshooting
For developers
Everything below is for people writing plugins and adapters in TypeScript.
Developer quick start
No platform account and no model key required.
npm create zhin-app my-bot -y
cd my-bot
pnpm dev
- Open console.zhin.dev.
- Enter the API address printed in the terminal (new projects use
http://127.0.0.1:8068) and theHTTP_TOKENfrom.env. - Open the Sandbox chat and send
/hello. You should get a reply.
-y accepts every default: a browser Sandbox (simulated chat) instead of a real platform, and no AI. Requirements: Node.js ≥22.19.0 and pnpm 9+. Something wrong? Run npx zhin doctor.
Full walkthrough: Quick start · Prefer not to install yet? Try the live demo.
[!IMPORTANT] Upgrading an existing bot from 1.1.13 or earlier? The Runtime now only accepts
configVersion: 2. Stop the Bot first, upgradezhin.js/@zhin.js/clito the latest, then runzhin migrate instances(preview) andzhin migrate instances --apply(backs up first). Full steps and restore: Upgrading to configVersion 2.
How a bot is put together
chat platform your project (a plugin) chat platform
QQ / Discord … ──▶ Adapter ──▶ Middleware ──▶ Command ──────────────▶ Adapter ──▶ reply
│ no command matched
└──▶ AI Agent (optional) ──▶ Tools
New to these terms? Read Core concepts at a glance — it explains every word the docs use, in plain language.
Writing features
A whole bot can be one file:
// bot.ts
import { definePlugin } from 'zhin.js'
import { defineCommand } from 'zhin.js/command'
export default definePlugin({
name: 'my-bot',
setup({ addCommand }) {
addCommand('hello', defineCommand({
description: 'Say hello',
execute: () => 'Hello from Zhin!',
}))
},
})
As it grows, move each capability into its own file. The folder path is the name, and the file registers itself:
// commands/remind/index.ts → /remind 10 stretch
import { defineCommand } from 'zhin.js/command'
export default defineCommand({
description: 'Create a reminder',
params: {
minutes: { type: 'integer', min: 1, max: 1440 },
note: { type: 'text', default: 'Take a break' },
},
options: { quiet: { type: 'boolean', default: false } }, // --quiet
execute: ({ params, options }) =>
options.quiet ? 'OK' : `OK, I'll remind you in ${params.minutes} min: ${params.note}`,
})
my-bot/
├── package.json # "zhin" field: entry and child plugins (what is installed)
├── zhin.config.yml # port, platform credentials, models (how it is configured)
├── .env # secrets: HTTP_TOKEN, API keys
├── plugin.ts # entry: definePlugin()
├── commands/ # /commands — folder path = command name
├── middlewares/ # runs on every message
├── components/ # reusable JSX message cards
├── schedules/ # scheduled jobs
├── tools/ # functions the AI may call (optional)
└── pages/ # custom Console pages
Next: Write your first plugin · All convention folders · Commands in depth
Connect a real platform
npx zhin setup --adapters # pick platforms, enter credentials
pnpm install && pnpm dev
Each adapter has a maturity tier (Stable / Advanced / Experimental) and its own setup guide: Adapters overview.
Add AI (optional)
npx zhin setup --ai # choose a provider (OpenAI, Ollama, …) and write the config
pnpm install && pnpm dev
The wizard installs the Agent runtime and the tool / prompt features, and writes something like this to zhin.config.yml (keys go to .env):
ai:
enabled: true
providers:
openai-main:
sdk: openai
apiKey: ${AI_API_KEY}
agents:
zhin:
provider: openai-main
model: gpt-4o-mini
Messages that match no command now go to the model — in DMs by default, in groups with an ai: prefix or a mention. Give it abilities by adding files to tools/; permissions, approvals and file/network access are enforced by framework policy, not by the prompt.
Next: AI overview · Agent tools, Skills and Prompt Sections · AI Agent learning path
Install only what you need
Detailed table and sizes: Install tiers. Since 1.1, ZhinAgent / AIService are imported from zhin.js/agent / zhin.js/ai, not from zhin.js.
Documentation
Operators & group owners
Developers
Full site: zhin.js.org (Chinese by default; switch language in the nav).
CLI cheat sheet
npx zhin setup # add platforms, AI, database to an existing project
npx zhin doctor # diagnose Node, ports, tokens, manifest
npx @zhin.js/cli new my-plugin --standalone # scaffold a publishable plugin package
npx zhin search <keyword> # find community plugins
npx zhin install <name> # install and mount a plugin
All commands: CLI reference.
Packages
How the layers fit together: architecture · repo structure.
Contributing
git clone https://github.com/zhinjs/zhin.git
cd zhin
pnpm install && pnpm build
pnpm dev # runs examples/minimal-bot
Other entry points: pnpm --filter single-file-bot dev (one-file bot) and pnpm dev:test (maintainers' kitchen-sink test-bot, not a template). See the contributing guide for checks, conventions and the release flow.
