https://github.com/jinshuju/agent-miniprogram
A CLI tool that helps AI agents test and operate WeChat Mini Programs.
https://github.com/jinshuju/agent-miniprogram
ai-agent automation cli jinshuju testing typescript wechat-mini-program
Last synced: 16 days ago
JSON representation
A CLI tool that helps AI agents test and operate WeChat Mini Programs.
- Host: GitHub
- URL: https://github.com/jinshuju/agent-miniprogram
- Owner: jinshuju
- License: mit
- Created: 2026-03-04T04:11:56.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-22T07:37:53.000Z (about 1 month ago)
- Last Synced: 2026-05-22T15:31:50.818Z (about 1 month ago)
- Topics: ai-agent, automation, cli, jinshuju, testing, typescript, wechat-mini-program
- Language: TypeScript
- Homepage: https://github.com/jinshuju/agent-miniprogram#readme
- Size: 66.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/vercel/agent-browser) (ref system, token-efficient snapshots) and [Agent Device](https://github.com/callstack/agent-device) (daemon architecture, SKILL.md, .amp recordings).
## Install
```bash
npm install -g agent-miniprogram
```
## Prerequisites
1. [WeChat Developer Tools](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html) installed
2. In Developer Tools: **Settings → Security → Enable CLI/HTTP calls**
3. Node.js 18+
## Quick Start
```bash
# 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):
```text
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](skills/agent-miniprogram/SKILL.md) for the full reference.
| Command | Description |
|---------|-------------|
| `launch ` | 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 ` | Navigate to page |
| `back` | Go back |
| `tap ` | Tap element |
| `input ` | Type text |
| `scroll ` | Scroll element |
| `long-press ` | Long press |
| `swipe ` | Swipe gesture |
| `wait ` | Wait for element or time |
| `data [path]` | Read page.data |
| `eval ` | Run JS in AppService |
| `mock ` | Mock wx.* API |
| `diff snapshot` | Diff vs last snapshot |
| `record start/stop` | Record interactions |
| `replay ` | 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
```text
agent-mp
│
▼ HTTP POST /rpc (localhost:9430)
┌─────────────────────────┐
│ Daemon (Node.js) │ ~/.agent-miniprogram/daemon.json
│ - session state │ ~/.agent-miniprogram/refs.json
│ - ref registry │
└────────┬────────────────┘
│ WebSocket
▼
微信开发者工具 (miniprogram-automator)
│
▼
小程序（模拟器）
```
```bash
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