Documentation

Concepts

Agim (阿吉姆) is a single Node.js process that bridges messengers (WeChat, Feishu, DingTalk, Email) to native agents (Claude Code, Codex, OpenCode, Antigravity, Cursor — or the built-in Agim Agent, or any ACP endpoint). No Docker, no Redis — one process, 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.
• Four front-ends: IM (WeChat / Feishu / DingTalk / Email), the built-in web console, a terminal TUI (agim tui — pick an agent, save and resume sessions), and programmatic access over ACP — all sharing the same agent and session backend.
• Long-term memory: a per-user 5W1H fact store plus an auto-distilled persona summary injected into every prompt; SQLite + FTS5 by default, with optional vector recall (local BGE or an OpenAI-compatible endpoint) for synonym and cross-lingual lookup.

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.

Native agents

Each agent is a local command-line tool; the wizard checks whether it is installed with <cmd> --version and labels "installed / not installed" with install instructions.

Agim Agent (built-in)

Agim Agent is the built-in agent — just configure a large-model API and it works, nothing extra to install. It runs in-process and talks directly to any OpenAI-/Anthropic-compatible backend (DeepSeek / Kimi / Qwen / GLM / Ollama / vLLM / OpenAI / Anthropic), sharing the same approval bus, audit log, memory, and MCP tools as the command-line agents. What sets it apart is a set of in-process local tools plus a reliability layer built for an agent you run as the everyday default.

Tool suite

Reliability stack (four-layer early-stop / recap)

Agim Agent's loop is wrapped in four independent checks, escalating from mechanical to semantic. On a hit it stops early and renders a structured recap card (what happened, which tools ran, a suggested next step, and a way to switch agents) instead of pushing more useless output at you:

• Empty-reply retry — when a turn ends with no text but tool calls happened, it re-asks once with the same model and tools disabled, forcing a summary of what was just done.
• Max-iteration recap — when the iteration cap is hit, it reports progress and a next step instead of silently truncating.
• Stuck-loop detection — same tool, same error, same output three times in a row stops immediately (a mechanical check, no extra LLM cost).
• Off-track goal critic — after enough tool calls, a single cheap LLM call judges whether the work still serves the original goal; enabled by default only when an active /long_task goal exists.

Backend and role configuration is in the Configuration section below (`llmBackends` / `llmRoles`); the persona lives in `~/.agim-workspaces/native/AGENTS.md` and hot-reloads without a restart.

Slash commands

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

Long-running work & goals

A single IM message has a 30-minute hard ceiling; intermediate state is lost on timeout. Agim provides several mechanisms to manage work that crosses that line:

• Sustained goals — `/goal set <title>` or `/long_task <title>` sets one active goal for the thread; it is injected into every prompt to keep the agent on track. `/goal progress` logs progress, `/complete_goal` closes it. One active goal per thread.
• bgjob — Work expected to run longer than 10 minutes goes into a standalone script handed to bgjob (detached, resumable, progress on disk), free of the IM timeout. Agim Agent's `native_exec` recognizes and allows bgjob calls.
• /cron — Cron expressions trigger a stored prompt on any registered agent: daily reports, weekly digests, off-hours batches.
• /heartbeat — Periodically runs a DECIDE / EXECUTE / EVALUATE check so the agent can proactively decide whether the thread needs action.

When Agim Agent spins or drifts under a sustained goal, the reliability stack from the Agim Agent section (stuck-loop and off-track detection) stops early and recaps instead of burning the iteration budget.

Security & approval

Agent tool calls are gated by default, and sensitive data has several layers of interception. These defenses are enforced in the agim process, not left to the model's discretion:

• Approval bus — Tool calls that touch files, run shell, or hit the network surface an approval card; reply y / n / all. Timeout behavior is configurable (default deny; "user-away" mode switches to allow).
• Sensitive-path denylist — Hard-rejected before any read-only auto-allow: env files, ~/.ssh/, system password files, agim tokens, AGENTS.md / CLAUDE.md, env / printenv dumps, credentials.*, and more — not allowed even if an operator approves. Bash and native_exec share the same denylist.
• Outbound scrubbing — Before a message goes out, token-shaped substrings (agim / OpenAI / GitHub / Slack / AWS / Telegram / Discord / PEM / JWT) are replaced with [REDACTED].
• exec sandbox — `IMHUB_EXEC_SANDBOX=bwrap` (Linux, opt-in) runs native_exec inside a bubblewrap namespace, optionally with networking off.
• Platform blacklist + web auth — `IMHUB_PLATFORM_BLACKLIST` refuses to register named platforms at boot; the web console is token-gated by default with a 127.0.0.1 bypass.
• Admin allowlist — Service commands like `/restart` / `/stop` are limited to the `IMHUB_ADMIN_USERS` allowlist; first deploy uses a one-time bootstrap token for self-service admin setup.

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:

Web console

`agim` ships a local web console (binds 127.0.0.1 by default; the port is set at install time, get the URL with `/web`). Main pages:

• Chat — Talk to an agent in the browser; approval cards are answered by click (the button disables and shows status immediately, so it never looks unresponsive).
• Settings — Pick enabled messengers / agents, choose the default agent, configure model backends, external MCP, and remote ACP agents. Changes to enabled agents and the default agent take effect immediately on save, no restart.
• Security — Gathers approval policy, timeout behavior, platform blacklist, and related security switches on one page.
• Memory — Inspect / edit / export the long-term fact store and persona summary; rebuild the persona on demand.
• Viewer — Long replies become a `/v/<id>` short link viewed in the browser, avoiding IM truncation; supports local-proxy / cloudflared / remote-paste modes.

Terminal UI (TUI)

`agim tui` opens an Ink-based terminal chat UI: pick an agent and talk locally, with no IM attached. Useful for testing agent configuration on a server, running a quick conversation, or just as a local terminal assistant. Sessions are auto-saved under tui-sessions in AGIM_HOME and can be resumed any time.

Launch

In-app commands

Keys & input syntax

• Enter send · Esc cancel the running turn · ↑ / ↓ options / history · Tab autocomplete · Ctrl-P command palette · Ctrl-C exit.
• !<cmd> — run a bash command inline.
• @<file> — reference a file path; the agent can read it with its own tools.

Skills

A skill is an on-demand knowledge / script pack for the agent. Agim scans two locations: the operator's own `~/.agim/skills/<name>/SKILL.md` takes priority, with built-ins as fallback. Three-tier progressive disclosure keeps the context from filling up at once:

• Tier 1 — name + description, auto-injected into the system prompt every turn.
• Tier 2 — the SKILL.md body, pulled on demand via the read_skill tool.
• Tier 3 — scripts / references / assets, referenced by the body and read as ordinary files.

`/skill list|show|refresh` works in your IM; the web console has a skill editor. Both the command-line agents and Agim Agent access skills transparently through the read_skill tool. Discover / install more from skillhub.cn, the public skill marketplace.

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.

There is also agim tui , a local terminal chat UI — see the Terminal UI section above.

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)    │
│ Feishu         (Lark SDK WebSocket)              │
│ DingTalk       (Stream WebSocket + ASR baked in) │
│ Web Chat       (browser WebSocket)               │
│ Email          (SMTP, push-only)                 │
└───────────────────────┬──────────────────────────┘
                        │ MessageContext
                        ▼
                  Router + Session
                        │
                        ▼
                Approval bus (HITL)
                        │
                        ▼
                Agent adapters
       ┌─────────────┼─────────────────┐
   Local CLI      In-process        Remote ACP
 (Claude / Codex /  Agim Agent    (HTTP /events)
  OpenCode /        (OpenAI /
  Antigravity /      Anthropic
  Cursor)            compat)