Documentation

Concepts

Agim is a lightweight hub that connects messengers, the Web console, and agents. You can send a message from WeChat, Feishu, DingTalk, Telegram, or the Web console, then let Claude Code, Codex, Cursor, Kimi Code, Qoder, PI, MiMo Code, Antigravity, OpenCode, or the built-in Agim Agent handle the work.

It does not replace the agents you already use or force your workflow into a heavy backend. Agim handles routing, sessions, approval, memory, recovery, and audit so “send a task in chat” becomes a reliable operating model.

• Entry points: IM, Web console, and terminal TUI all use the same service.
• Agent dispatch: keep one sticky agent or switch agents inside a conversation.
• Safety controls: file, shell, and network actions can ask for approval first.
• Long-running work: reminders, goals, schedules, background jobs, and recovery are handled by Agim.
• Local data: configuration, sessions, memory, and audit logs live under ~/.agim by default.

Quick start

For the full script, npm, and source install paths, see the install page . For a first run, get Web plus one agent working before connecting messengers.

npm install -g agim-cli
agim go
agim web
agim doctor

• agim go checks the environment, helps configure one usable agent, and starts the service.
• If Claude Code, Codex, Cursor, or another CLI agent is already installed, Agim will try to detect it.
• If no CLI agent is installed yet, configure a model API and use the built-in Agim Agent.
• Once Web chat works, connect WeChat, Feishu, DingTalk, Telegram, or email notifications from Settings.

Messengers

You do not need to enable every messenger at once. Start with the channel you use most, verify message delivery, approvals, and agent replies, then add more entry points.

A practical rollout order is: Web console first, then IM; direct messages first, then groups; text first, then files, images, and voice. It makes troubleshooting much easier.

Mainstream agents

Agim puts different agents on the same message bus. You can set a default agent or switch within a conversation. These are the main supported backends today.

Pick the agent you know best as the default. Once stable, add the others as specialist tools: Codex for tests, Claude Code for deeper planning, Agim Agent for everyday Q&A.

Agim Agent (built-in)

Agim Agent is built in. It does not require an external CLI. Configure a model API and it can talk to OpenAI-compatible, Anthropic-compatible, Ollama, vLLM, or common China-friendly model providers.

It is a good default assistant for Q&A, summaries, reminders, memory, lightweight files, and tool calls. If you have not installed Claude Code, Codex, Cursor, or another mainstream agent yet, Agim Agent lets the whole system run first.

• Model settings live in llmBackends and llmRoles; secrets are stored separately.
• Its role file can live at ~/.agim-workspaces/native/AGENTS.md and reloads without a restart.
• It uses the same approval, audit, memory, reminder, and recovery features as the CLI agents.

Common commands

These are the commands you will use most often. In practice, you do not need to memorize all of them; many capabilities can also be triggered in natural language.

Long-running work & goals

IM is great for assigning work, but long-running work should not depend on one chat message. Agim models it as recoverable goals, reminders, schedules, background jobs, and outbound delivery.

• Goals: use /goal or /long_task to keep the current thread focused on one sustained objective.
• Reminders: use /remind for one-shot or recurring reminders, or ask the agent in natural language.
• Schedules: use /cron to run an agent periodically for reports, checks, or batch work.
• Background jobs: longer tasks enter the job board and can be reviewed from Web or /job.
• Reliable delivery: replies go through a local outbox before reaching IM or Web, so restarts can recover.

In daily use, the point is simple: you can break complex work into steps, and Agim keeps enough state to bring the result back to the original conversation.

Security & approval

Agim does not rely on the model “being careful.” Safety is enforced at the service layer, between the agent and the real system.

• Approval: file writes, shell commands, and network access can surface an approval card first.
• Sensitive-path protection: secrets, config, system accounts, and agent instruction files are blocked from being read out and sent back to IM.
• Web auth: the Web console supports token access control. Put public deployments behind a reverse proxy and TLS.
• Admins: restart, stop, and high-risk settings should be limited to administrator accounts.
• Audit: invocations, results, latency, and errors are recorded for review and troubleshooting.

For local personal use, defaults are a good start. For a team or server deployment, configure admins, Web access, and backups early.

Configuration

Most settings can be changed through agim go, agim config, or Web Settings. You usually only need the files for automation, migration, or troubleshooting.

Recommended practice: let the wizard write config, use Web to inspect status, and back up ~/.agim before manual edits.

Web console

The Web console is the best place for first setup and day-to-day status checks. It is more than chat: it also covers configuration, audit, and task review.

• Chat: talk to an agent in the browser and verify model, approval, and reply delivery.
• Settings: enable messengers, choose the default agent, configure model APIs, and manage remote agents.
• Tasks: review long-running tasks, schedules, background jobs, and retries.
• Memory: inspect and maintain facts, memos, and user profile memory.
• Audit: troubleshoot which agent ran, what happened, and whether it failed.

For local use, open it directly. For a server, expose it through a reverse proxy with HTTPS and keep token auth enabled.

Terminal UI (TUI)

agim tui is a local terminal chat interface. It does not depend on IM and is useful for server-side debugging, model setup checks, or a quick local conversation.

                agim tui
agim tui --agent codex
agim tui --agent native
agim tui --resume last
              

TUI is especially useful for troubleshooting: if TUI works but IM does not, check messenger credentials or callbacks. If TUI also fails, check agent installation, login, and model settings first.

Skills

A skill is a reusable capability pack for agents, usually a SKILL.md plus scripts, references, or templates. It is for stable working methods you do not want to repeat in every chat.

• Place a skill at ~/.agim/skills/<name>/SKILL.md, and Agim can let agents read it when needed.
• A skill can describe procedures, constraints, examples, and referenced scripts or assets.
• CLI agents and Agim Agent can use the same skill set.

Examples: daily reports, PR review rules, customer support tone, and internal system procedures.

Service lifecycle

The common path is to get Agim running with agim go, then choose foreground, background, or systemd depending on where it runs.

For routine checks, start with agim status and agim doctor . To change setup, use agim config or Web Settings.

Architecture

From a user perspective, Agim works like this: entry points receive messages, routing selects an agent, the safety layer handles approval and audit, then delivery sends the result back where it came from.

IM / Web / TUI
     │
     ▼
Agim Router ── Session / Memory / Goal
     │
     ▼
Approval / Audit / Recovery
     │
     ▼
Agents: CLI Agent / Agim Agent / Remote Agent
     │
     ▼
Outbox → IM / Web / Notification

That is why the recommended first step is Web plus one agent. Once the core path works, add more messengers, agents, and team rules.