Agent Miniprogram

A CLI tool for AI-driven WeChat miniprogram automation testing. Designed for use with AI agents like Claude Code.

Inspired by Agent Browser (ref system, token-efficient snapshots) and Agent Device (daemon architecture, SKILL.md, .amp recordings).

Install

npm install -g agent-miniprogram

Prerequisites

1. WeChat Developer Tools installed
2. In Developer Tools: Settings → Security → Enable CLI/HTTP calls
3. Node.js 18+

Quick Start

# Start the daemon
agent-mp daemon

# Launch DevTools and connect
agent-mp launch /path/to/miniprogram

# Get snapshot (ref-annotated WXML tree)
agent-mp snapshot

# Tap an element by ref
agent-mp tap @e5

# Type into an input
agent-mp input @e3 "13800138000"

Snapshot Format

agent-mp snapshot outputs a compact, ref-annotated tree (~200-400 tokens):

Page: /pages/index/index

[view @e1]
  [image @e2] src="/img/logo.png"
  [text @e3] "欢迎登录"
[form @e4]
  [input @e5] placeholder="手机号" (bindinput=onPhoneInput)
  [input @e6] type="password" placeholder="密码" (bindinput=onPasswordInput)
  [button @e7] "登录" (bindtap=onLogin)
[navigator @e8] → /pages/register/index "注册账号"

• @eN refs are assigned per snapshot call and persist in ~/.agent-miniprogram/refs.json
• Only semantically meaningful nodes are shown (text, events, attributes)
• Pure layout containers are folded

Commands

See skills/agent-miniprogram/SKILL.md for the full reference.

| Command | Description | |---------|-------------| | launch <path> | Launch DevTools and connect | | connect | Connect to running DevTools | | close | Close connection | | status | Show daemon status | | snapshot [--data] | WXML tree with refs | | screenshot | Take screenshot | | navigate <url> | Navigate to page | | back | Go back | | tap <ref> | Tap element | | input <ref> <text> | Type text | | scroll <ref> | Scroll element | | long-press <ref> | Long press | | swipe <ref> <dir> | Swipe gesture | | wait <ref\|ms> | Wait for element or time | | data [path] | Read page.data | | eval <code> | Run JS in AppService | | mock <api> <json> | Mock wx.* API | | diff snapshot | Diff vs last snapshot | | record start/stop | Record interactions | | replay <file.amp> | Replay recording |

Claude Code Integration

Copy or symlink skills/agent-miniprogram/SKILL.md to your Claude Code skills directory, or reference it in your project's CLAUDE.md.

Development

agent-mp <command>
    │
    ▼ HTTP POST /rpc (localhost:9430)
┌─────────────────────────┐
│   Daemon (Node.js)       │  ~/.agent-miniprogram/daemon.json
│   - session state        │  ~/.agent-miniprogram/refs.json
│   - ref registry         │
└─────────┬───────────────┘
          │ WebSocket
          ▼
  微信开发者工具 (miniprogram-automator)
          │
          ▼
    小程序（模拟器）

git clone https://github.com/michaelneale/agent-miniprogram
cd agent-miniprogram
npm install

# Start daemon (dev mode)
npm run daemon
# or
npx tsx src/daemon/server.ts

# Run tests
npm test

File Paths

• ~/.agent-miniprogram/daemon.json — daemon runtime state
• ~/.agent-miniprogram/refs.json — element ref registry
• ~/.agent-miniprogram/last-snapshot.txt — last snapshot (for diff)
• ~/.agent-miniprogram/screenshot.png — default screenshot path