MetaBot

Infrastructure for building a supervised, self-improving agent organization.

English | 中文

Why

Claude Code is the most capable AI coding agent — but it's trapped in your laptop terminal.

MetaBot sets it free. It gives every agent a Claude Code brain, persistent shared memory, the ability to create new agents, and a communication bus. All accessible from Feishu or Telegram on your phone.

We built MetaBot to run XVI Robotics as an agent-native company — a small team of humans supervising an organization of self-improving AI agents. This is the infrastructure that makes it possible.

How It Works

┌──────────────────────────────────────────────────────────┐
│                       MetaBot                            │
│                                                          │
│  ┌──────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐  │
│  │ MetaSkill│ │MetaMemory │ │IM Bridge │ │ Scheduler │  │
│  │  Agent   │ │  Shared   │ │ Feishu + │ │   Cron    │  │
│  │ Factory  │ │ Knowledge │ │ Telegram │ │   Tasks   │  │
│  └────┬─────┘ └─────┬─────┘ └────┬─────┘ └─────┬─────┘  │
│       └──────────────┴────────────┴─────────────┘        │
│                       ↕                                  │
│            Claude Code Agent SDK                         │
│         (bypassPermissions, streaming)                   │
│                       ↕                                  │
│             HTTP API (:9100) — Agent Bus                 │
│        task delegation · bot CRUD · scheduling           │
└──────────────────────────────────────────────────────────┘

Three pillars of a self-improving agent organization:

Core Components

Install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/xvirobotics/metabot/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/xvirobotics/metabot/main/install.ps1 | iex

The installer walks you through: working directory → Claude auth → IM credentials → auto-start with PM2.

Windows notes: The PowerShell installer auto-detects winget/choco/scoop for Node.js installation. CLI tools (mm, mb, metabot, fd) are installed with .cmd wrappers and require Git for Windows (provides Git Bash).

git clone https://github.com/xvirobotics/metabot.git
cd metabot && npm install
cp bots.example.json bots.json   # edit with your bot configs
cp .env.example .env              # edit global settings
npm run dev

Quick Setup

Telegram (30 seconds):

1. Message @BotFather → /newbot → copy token
2. Add to bots.json → done (long polling, no webhooks)

Feishu/Lark (detailed guide):

1. Create app at open.feishu.cn → add Bot capability
2. Enable permissions: im:message, im:message:readonly, im:resource, docx:document:readonly, wiki:wiki (for doc reading & wiki sync)
3. Start MetaBot, then enable persistent connection + im.message.receive_v1 event
4. Publish the app

What You Can Build

• Solo AI developer — full Claude Code from your phone, bound to your project
• Multi-agent team — frontend bot, backend bot, infra bot, each in their own workspace, talking via the Agent Bus
• Self-growing organization — a manager bot that creates new agents on demand, assigns tasks, schedules follow-ups
• Autonomous research pipeline — agents that search, analyze, save findings to MetaMemory, and schedule next steps

Configuration

bots.json — define your bots:

{
  "feishuBots": [{
    "name": "metabot",
    "feishuAppId": "cli_xxx",
    "feishuAppSecret": "...",
    "defaultWorkingDirectory": "/home/user/project"
  }],
  "telegramBots": [{
    "name": "tg-bot",
    "telegramBotToken": "123456:ABC...",
    "defaultWorkingDirectory": "/home/user/project"
  }]
}

ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic    # Kimi/Moonshot
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic   # DeepSeek
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic       # GLM/Zhipu
ANTHROPIC_AUTH_TOKEN=your-key

Security

MetaBot runs Claude Code in bypassPermissions mode — no interactive approval. Understand the implications:

• Claude has full read/write/execute access to the working directory
• Control access via Feishu/Telegram platform settings (app visibility, group membership)
• Use allowedTools to restrict capabilities (remove Bash for read-only)
• Use maxBudgetUsd to cap cost per request
• API_SECRET enables Bearer auth on both the API server and MetaMemory
• MetaMemory supports folder-level ACL: set MEMORY_ADMIN_TOKEN and MEMORY_TOKEN for dual-role access. Admin sees all folders; reader only sees folders with visibility: shared. Use PUT /api/folders/:id with {"visibility":"private"} to lock a folder

Chat Commands

API Reference

CLI Tools

The installer places metabot, mm, mb, and fd (Feishu bots only) executables in ~/.local/bin/ (Linux/macOS) or %USERPROFILE%\.local\bin\ with .cmd wrappers (Windows) — available immediately.

# MetaBot management
metabot update                      # pull latest, rebuild, restart
metabot start                       # start with PM2
metabot stop                        # stop
metabot restart                     # restart
metabot logs                        # view live logs
metabot status                      # PM2 process status

# MetaMemory — read
mm search "deployment guide"        # full-text search
mm list                             # list documents
mm folders                          # folder tree
mm path /projects/my-doc            # get doc by path

# MetaMemory — write
echo '# Notes' | mm create "Title" --folder ID --tags "dev"
echo '# Updated' | mm update DOC_ID
mm mkdir "new-folder"               # create folder
mm delete DOC_ID                    # delete document

# Feishu Document Reader (Feishu bots only)
fd read <feishu-url>                # read document by URL (docx or wiki)
fd read-id <docId>                  # read document by ID
fd info <feishu-url>                # get document metadata

# Agent Bus
mb bots                             # list all bots
mb task <bot> <chatId> <prompt>     # delegate task
mb schedule list                    # list scheduled tasks
mb schedule cron <bot> <chatId> '<cron>' <prompt>  # recurring task
mb schedule pause <id>              # pause recurring task
mb schedule resume <id>             # resume recurring task
mb stats                            # cost & usage stats
mb health                           # status check

Development

npm run dev          # Hot-reload dev server (tsx)
npm test             # Run tests (vitest, 155 tests)
npm run lint         # ESLint check
npm run format       # Prettier format
npm run build        # TypeScript compile to dist/

Production

metabot start                       # or: pm2 start ecosystem.config.cjs
metabot update                      # pull + rebuild + restart
pm2 startup && pm2 save             # auto-start on boot

FAQ

No public IP needed? — Correct. Feishu uses WebSocket, Telegram uses long polling.

Non-Claude models? — Yes. Any Anthropic-compatible API (Kimi, DeepSeek, GLM, etc.)

Agent communication? — Currently synchronous request-response. Async bidirectional protocols are on the roadmap.

About

MetaBot is built by XVI Robotics, where we develop humanoid robot brains. We use MetaBot internally to run our company as an agent-native organization — a small team of humans supervising self-improving AI agents. We open-sourced it because we believe this is how companies will work in the future.

License

MIT