Agent Miniprogram

A CLI tool that helps AI agents test and operate WeChat Mini Programs. Designed for use with AI agents like Claude Code.

Who is this for?

• Developers who build and test WeChat Mini Programs
• Teams exploring AI-assisted UI testing for Mini Programs
• AI agents that need a stable CLI interface for Mini Program snapshots and interactions

Project status

This project is maintained by the Jinshuju team. It is suitable for internal automation, AI-assisted testing workflows, and early developer adoption.

Issues and suggestions are welcome in this repository.

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/jinshuju/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

License

MIT