imtoagent — IM ↔ Agent Unified Gateway

Connect Feishu, Telegram, personal WeChat, and WeCom to AI coding agents like Claude Code, Codex (GPT), OpenCode, and more.

One gateway, multiple IMs, multiple agents, unified port proxy.

Architecture

飞书/Telegram/微信/企微 → IM Registry 工厂 → Bot 实例
                                          → AgentRuntime SDK → Agent Adapter
                                                             → 统一 Proxy (:18899) → 上游模型

Supported IM Adapters

Supported Agent Backends

Quick Start

Prerequisites

• Bun runtime (≥1.0.0): brew install oven-sh/bun/bun
• macOS / Linux
• At least one Agent backend (see table below; can be installed before or after imtoagent)

Installation

Method 1: npm global install (recommended)

npm install -g imtoagent

After installation, it automatically checks whether initial configuration is needed. An interactive terminal will guide you through the setup wizard.

Method 2: Source install

git clone https://github.com/YOUR_USERNAME/imtoagent.git
cd imtoagent
bun install
bun run bin/imtoagent setup

First-Time Configuration

imtoagent setup

The interactive setup wizard guides you through:

1. Configure Bot — Select IM platform + Agent backend
2. Configure Model Providers — Add API credentials (DeepSeek, Dashscope, etc.)
3. Generate Soul Files — Create rules.md / identity.md etc. for each Bot
4. Write Config Files — Auto-generate ~/.imtoagent/config.json

Feishu Bot Requirements

• Feishu App ID (cli_...)
• Feishu App Secret
• Feishu app must enable: Bot, Event Subscription, Message Send/Receive permissions

Telegram Bot Requirements

• Telegram Bot Token (obtain from @BotFather)
• Optional: Proxy address (e.g., http://127.0.0.1:7890)

Personal WeChat

• QR code automatically pops up on first run of imtoagent start
• Scan with your phone's WeChat to complete binding

Start the Gateway

imtoagent start     # Start in background
imtoagent status    # Check running status
imtoagent stop      # Stop the gateway

Auto-Start on Boot (macOS launchd)

# Create launchd configuration
cat > ~/Library/LaunchAgents/com.imtoagent.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.imtoagent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/bun</string>
        <string>run</string>
        <string>/usr/local/lib/node_modules/imtoagent/index.ts</string>
        <string>daemon</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/$USER/.imtoagent</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
    </dict>
    <key>StandardOutPath</key>
    <string>/Users/$USER/.imtoagent/logs/launchd.out.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/$USER/.imtoagent/logs/launchd.err.log</string>
</dict>
</plist>
EOF

# Load
launchctl load ~/Library/LaunchAgents/com.imtoagent.plist

Common Commands

Built-In Gateway Commands

Send to the Bot in IM chat:

Project Structure

imtoagent/
├── index.ts                    # Entry — IM Registry + Bot construction + Proxy startup
├── bin/imtoagent               # CLI command entry point
├── modules/
│   ├── core/                   # SDK Core
│   │   ├── AgentRuntime.ts     # Message processing hub
│   │   ├── AgentAdapter.ts     # Unified Agent backend abstraction
│   │   ├── SessionManager.ts   # Session persistence
│   │   └── types.ts            # Type definitions
│   ├── im/                     # IM adapters
│   │   ├── feishu.ts           # Feishu
│   │   ├── telegram.ts         # Telegram
│   │   ├── wechat.ts           # Personal WeChat
│   │   └── wecom.ts            # WeCom
│   ├── agent/                  # Agent backends
│   │   ├── claude-adapter.ts   # Claude Code
│   │   ├── codex-adapter.ts    # Codex
│   │   └── opencode-adapter.ts # OpenCode
│   ├── proxy/                  # Unified proxy
│   │   └── anthropic-proxy.ts  # :18899 Anthropic format proxy
│   ├── cli/                    # CLI
│   │   └── setup.ts            # Interactive setup wizard
│   └── utils/
│       └── paths.ts            # Path resolution + auto-init
├── scripts/
│   └── postinstall.ts          # Post-npm-install guidance
├── templates/                  # Config templates
│   ├── config.template.json
│   ├── providers.template.json
│   ├── opencode.template.json
│   └── soul.template/
└── README.md

Data Directory

All runtime data is stored centrally in ~/.imtoagent/:

~/.imtoagent/
├── config.json          # Main config (Bot + providers + system)
├── providers.json       # Model provider config
├── opencode.json        # OpenCode config
├── sessions/            # Session persistence
├── logs/                # Runtime logs
└── soul/                # Soul files (one directory per Bot)
    ├── ClaudeBot/
    ├── CodexBot/
    └── ...

Development

bun install
bun run index.ts          # Run directly
bun run bin/imtoagent setup  # Run setup wizard

License

MIT