Zhin

What is Zhin.js?

Zhin.js is a framework for building bots that live in chat apps — 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.ts is the /hello command. 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.

Quick start

No platform account and no model key required.

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

1. Open console.zhin.dev.
2. Enter the API address printed in the terminal (new projects use http://127.0.0.1:8068) and the HTTP_TOKEN from .env.
3. 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.

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

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.

License

MIT