@catpi-miti/miti-claude-code-channel

Claude Code Channels plugin: connect Miti App to your local Claude Code session.

Prerequisites

• Claude Code v2.1.80+ (Channels research preview)
• Miti Agent App ID / Secret
• Node.js ≥ 22

Published install (npm)

Package: @catpi-miti/miti-claude-code-channel · current 0.1.3

npm install @catpi-miti/miti-claude-code-channel@latest

Full steps for production users, QA (t1), and maintainer release:

• Users (Windows / macOS): claude-code-user-install.md
• Maintainers: PUBLISHING.md

Quick start (production):

mkdir -p ~/.claude/channels/miti
# write credentials.json with appId, appSecret, apiBaseUrl https://www.miti.chat/chat

cd /path/to/your-project
claude --dangerously-skip-permissions \
  --plugin-dir ./node_modules/@catpi-miti/miti-claude-code-channel \
  --dangerously-load-development-channels plugin:miti@inline

Or use marketplace (recommended):

claude plugin marketplace add stocki-ai/miti-claude-marketplace
claude plugin install miti@miti-claude-marketplace

See claude-code-user-install.md for full steps and troubleshooting.

Development install (from source)

cd miti-claude-code-channel
npm install && npm run build

mkdir -p ~/.claude/channels/miti
cat > ~/.claude/channels/miti/credentials.json <<'EOF'
{
  "appId": "your_app_id",
  "appSecret": "your_app_secret",
  "apiBaseUrl": "https://www.miti.chat/chat"
}
EOF

# 在工作目录启动 session（Windows 路径请自行替换）
cd /path/to/your-project
claude --debug-file /tmp/miti-claude-debug.log \
  --dangerously-skip-permissions \
  --plugin-dir /path/to/miti-claude-code-channel \
  --dangerously-load-development-channels plugin:miti@inline

Windows PowerShell 示例：

cd C:\pai
claude --debug-file "C:\pai\miti-claude-debug.log" `
  --dangerously-skip-permissions `
  --plugin-dir "C:\pai\miti-claude-code-channel" `
  --dangerously-load-development-channels plugin:miti@inline

启动后在 Claude 内 /mcp 确认 plugin:miti:miti 为 ✓ Connected。

• 发版与用户安装：PUBLISHING.md
• 源码联调 QA：claude-code-testing.md

Channels 参数： 必须是 plugin:miti@inline（--plugin-dir 对应 marketplace 名 inline），不能写裸 miti 或 plugin:miti@local。

工具权限： 不在 Miti 里做远程审批。从手机遥控且希望 Bash/Write/Edit 不弹窗时，启动时加 --dangerously-skip-permissions（即 bypassPermissions）。须配合 pairing/allowlist，详见设计文档 §10。

如果你更喜欢环境变量，MITI_APP_ID / MITI_APP_SECRET / MITI_API_BASE_URL 依然可用，并且优先级高于 ~/.claude/channels/miti/credentials.json。未设置时默认 https://www.miti.chat/chat。内部 QA 测 t1 见 claude-code-testing.md。

Pairing

单聊默认需要 pairing；群 @ 默认不需要 pairing（groupAccessPolicy=open）。仅当需要收紧群 @ 时设置 MITI_CLAUDE_CHANNEL_GROUP_ACCESS=pairing。

1. User sends pair to the Miti Bot（单聊）
2. Bot replies with a 6-digit code
3. On the machine running Claude Code (in a system terminal, not inside the Claude chat):

# macOS / Linux
npx miti-claude-channel-pair 123456

# Windows（推荐，无需全局安装）
node dist/pair-cli.js 123456

# Windows（需先在插件目录 npm link）
miti-claude-channel-pair 123456

4. Send messages from Miti — they appear in the current Claude Code session
5. Claude replies via the reply tool → Miti stream_full Markdown

pairing / hybrid 模式下，任何知道 Bot 的人都可以发送 pair 申请配对码；真正授权发生在本机执行 miti-claude-channel-pair <code> 这一步（主要影响单聊）。

Group @ access (default: no pairing)

| Scenario | Default local pairing | |----------|----------------------| | Direct message | Required (pair + miti-claude-channel-pair) | | Group @ | Not required (MITI_CLAUDE_CHANNEL_GROUP_ACCESS defaults to open) |

To require pairing for group @ as well:

export MITI_CLAUDE_CHANNEL_GROUP_ACCESS=pairing

Or add to .mcp.json env and restart the Claude session.

Claude account requirement

Channels require official Claude authentication (claude.ai or Anthropic Console API key).
Custom ANTHROPIC_BASE_URL (e.g. LiteLLM gateway) does not enable Channels — you will see Channel notifications skipped: channels feature is not currently available in debug logs.

Full QA guide

See miti-agent-docs/claude-code-testing.md for the complete end-to-end flow (Miti App → build → credentials → start session → pairing → troubleshooting).

Config notes

• .mcp.json 内置了 MITI_CLAUDE_CHANNEL_CONFIG_FILE，便于 GUI 启动时不给 shell 环境也能读到凭据；不在包内写死 MITI_API_BASE_URL，默认生产基址为 https://www.miti.chat/chat。
• .mcp.json 使用 ${CLAUDE_PLUGIN_ROOT}/dist/server.js，从任意目录 --plugin-dir 启动均可连通。
• 反向验证也已确认：如果脱离插件根目录直接执行 node ./dist/server.js，相对路径会失败。因此该写法的前提是 Claude 的插件加载行为，而不是 Node 自身能从任意目录解析。
• Windows / GUI 启动场景下，优先使用 ~/.claude/channels/miti/credentials.json；不要假设 Claude 会继承 PowerShell 里临时设置的环境变量。
• WebSocket 连接同时携带 Authorization: Bearer ... 和 ?token=...，兼容文档里的两种网关鉴权方式。
• 打包产物验证时，只有在包内生产依赖已安装后，claude mcp list 才会连通；发布包必须确保运行时依赖完整可用。
• 当前后端只稳定推送群聊 @ 文本；群聊 @ 图片仍按已知限制处理，暂不作为联调验收项。

Design

See miti-agent-docs/claude-code-channels-design.md.