Documentation

Concepts

Agim (阿吉姆) is a single Node.js process that bridges messengers (WeChat, Telegram, Feishu, DingTalk, Discord, Email) to AI agents (Claude Code, OpenCode, Codex, Copilot, or any ACP endpoint). No Docker, no Redis — one binary, one config dir.

• Sessions are keyed by platform:channel:thread and remember the last active agent, model, and message history. Idle for 30 minutes → auto-archive.
• Intent classifier picks an agent from casual chat without a slash prefix (bilingual zh/en keyword heuristics), then sticky-locks the choice for a few turns.
• Approval bus intercepts agent tool calls that write files, run shell, or hit the network. A card surfaces in your IM; reply y/n/all to gate the call.
• Persistent state lives in SQLite under ~/.agim/ (legacy 0.x installs keep using ~/.im-hub/) — jobs.db, memos.db, reminders.db, audit.db plus session files. Survives restarts; 30-day TTL on most.

Quick start

Three install paths are documented in detail at the install page。 Shortest happy path:

npm install -g agim-cli      # requires Node ≥ 18
agim                         # bilingual arrow-key wizard (recommended)
agim start                   # start in foreground

The wizard walks: pick language → pick which messengers to enable → run each one's setup (WeChat QR scan / Feishu App Secret / DingTalk ClientID …) → pick which agents to enable → configure SMTP (reminder email) / Baidu Maps AK (geocoding).

Messengers

Each messenger has its own submenu in the wizard with status, Configure, Re-configure, and Remove. Credentials persist to ~/.agim/config.json (legacy installs: ~/.im-hub/config.json; chmod 600).

DingTalk specifics: must create an "Enterprise Internal App" with Stream mode enabled (NOT a "group webhook bot" — those are push-only). A 1-person company works; register a personal enterprise. DingTalk never delivers native location messages to bots — use /memo here for the capture-link flow, or just type an address and let the agent geocode via Baidu Maps.

AI agents

Each agent maps to a local CLI binary; the wizard probes installation with <cmd> --version and labels "installed / not installed" with install instructions.

Slash commands

All slash commands are platform-agnostic. Most map to agent MCP tools, so natural-language phrasings trigger the same capability.

Configuration

Agim reads from three sources, in priority order:

1. ~/.agim/config.json (legacy installs: ~/.im-hub/config.json) — Primary config: enabled messengers, agents, defaultAgent, per-messenger credential objects, acpAgents list. chmod 600, written by the wizard.
2. ~/.agim/env (or ~/.im-hub/env) — Simple KEY=value file for SMTP credentials and Baidu Maps AK. chmod 600. Loaded by systemd unit via EnvironmentFile=.
3. process.env — Runtime process environment; used as a fallback by the wizard when neither file source has the key (systemd `Environment=` lines also surface here).

Frequently-used environment variables:

Service lifecycle

Three run modes, auto-detected:

• systemd — Installer (when run as root) drops /etc/systemd/system/agim.service (legacy: im-hub.service). Use systemctl or agim restart to manage.
• Background daemon — agim start --bg uses nohup + setsid + pid file. Cross-platform (Linux / macOS / WSL2).
• Foreground — agim start tied to your terminal, Ctrl-C to stop.

agim status detects current mode + pid + uptime + web URL in one shot.

Architecture

Inbound messages are normalized then handed to the router; router picks an agent; agent output goes back out via the originating messenger.

┌─ Messenger ingress ──────────────────────────────┐
│ WeChat iLink   (long-poll + image/voice/file)    │
│ Telegram       (grammy + photo/voice/audio)      │
│ Feishu         (Lark SDK WebSocket)              │
│ DingTalk       (Stream WebSocket + ASR baked in) │
│ Discord        (discord.js Gateway)              │
│ Web Chat       (browser WebSocket)               │
└───────────────────────┬──────────────────────────┘
                        │ MessageContext
                        ▼
                  Router + Session
                        │
                        ▼
                Approval bus (HITL)
                        │
                        ▼
                Agent adapters
            ┌────────────┴────────────┐
        Local CLI                 Remote ACP
   (Claude / Codex / OC / Co)  (HTTP /events)

Where to get help

• GitHub README — github.com/benking007/imhub (bilingual; long-form install / config / command reference).
• CHANGELOG — full version history。
• Issue tracker — github.com/benking007/imhub/issues。