From zero to your first AI tap.
Seven steps. Most people finish in 10 to 20 minutes, mostly waiting for the Android emulator to download. You don't need to know Python or Android.
- macOS · tested
- Windows · beta
- Linux · beta
- Free, up to 3 devices
Get an Android device 5–15 min
TapHerd controls any Android device your computer can reach with Android's adb tool. The easiest is a free Pixel emulator from Google. A real phone works too.
Option A: a free emulator (recommended)
- Download Android Studio from developer.android.com/studio and install it.
- Open it and choose the Standard setup. It downloads the emulator and
adb. - Open More Actions → Virtual Device Manager, then + → Create Virtual Device.
- Pick a Pixel with the Play Store icon, and a Google Play image at API 34 or later.
On Apple chips choose
arm64-v8a; on Intel Macs,x86_64. Choosex86_64. Choosex86_64. - Press Play and wait for the home screen.
The emulator needs virtualization. Turn on VT-x or AMD-V in your BIOS, then turn on Windows Hypervisor Platform in Turn Windows features on or off, and restart.
The emulator needs KVM. Check with ls -l /dev/kvm, and add yourself to the kvm group if needed.
Option B: your own Android phone
- Open Settings → About phone and tap Build number seven times.
- Open Settings → System → Developer options and turn on USB debugging.
- Connect it with a data cable. Some cables only charge.
- Unlock the phone and accept Allow USB debugging. Tick Always allow.
Most phones need their maker's USB driver on Windows. Pixel phones use the Google USB Driver from Android Studio's SDK Manager.
If adb says permission denied, add a udev rule. How
Want to post to apps like TikTok, Instagram, or YouTube? Sign in to the Play Store on the emulator, install the apps, and sign in to your own accounts on the device yourself. TapHerd never asks for passwords.
Install TapHerd 1–2 min
Open Terminal (press ⌘ Space, type Terminal) and paste:
curl -LsSf https://raw.githubusercontent.com/GreenPeaas/tapherd/main/scripts/install.sh | shOpen PowerShell from the Start menu. You don't need administrator rights. Paste:
irm https://raw.githubusercontent.com/GreenPeaas/tapherd/main/scripts/install.ps1 | iexOpen a terminal and paste:
curl -LsSf https://raw.githubusercontent.com/GreenPeaas/tapherd/main/scripts/install.sh | shThe installer:
- Installs uv, a Python tool manager, for your user only.
- Checks for
adb. If it's missing, it shows the install command and asks first. Linux package managers needsudo; the installer explains why before asking. - Installs TapHerd and runs
tapherd doctor.
Prefer to install by hand?
Install uv, then:
uv tool install tapherd
tapherd doctorIf uv says TapHerd wasn't found right after a release, use uv tool install --exclude-newer-package tapherd=false tapherd. Recent uv versions wait a few days before installing new uploads.
Open a new terminal window afterwards so the tapherd command is found.
Check everything 30 sec
With the emulator or phone on, run:
tapherd doctorYou should see something like this. Your serials may differ.
Python 3.11.18
Android Debug Bridge version 1.0.41
Active and online: emulator-5554
TapHerd Free supports up to 3 active devices and 3 concurrent operations.If doctor says no device, unauthorized, or offline, it prints the next command to run. The fixes are below.
Connect your AI 2 min
TapHerd prints the exact settings for your AI app, then tells you where to paste them. Pick your app:
- In your project folder, save the settings as
.mcp.json:tapherd config mcp --client claude-code > .mcp.json - Start
claudein that folder and approve the tapherd server when asked. - Type
/mcpto check it shows as connected.
- Print the settings:
tapherd config mcp --client claude-desktop - In Claude Desktop, open Settings → Developer → Edit Config. That opens
~/Library/Application Support/Claude/claude_desktop_config.json.%APPDATA%\Claude\claude_desktop_config.json. nothing: Claude Desktop isn't available on Linux. Use Claude Code, Codex, or Cursor. - Add the
tapherdentry insidemcpServers. If other servers are there, keep them. - Quit Claude Desktop completely and open it again.
- Print the settings:
tapherd config mcp --client codex - Add the
[mcp_servers.tapherd]block to~/.codex/config.toml.%USERPROFILE%\.codex\config.toml.~/.codex/config.toml. - Start a new Codex session.
- Print the settings:
tapherd config mcp --client cursor - Add the
tapherdentry to~/.cursor/mcp.json%USERPROFILE%\.cursor\mcp.json~/.cursor/mcp.jsonfor every project, or.cursor/mcp.jsonfor one. - Reload Cursor and check TapHerd is enabled under MCP settings.
Always paste what your tapherd config mcp prints. It points at the Python and adb on your computer. All details
Your first AI tap 1 min
Ask your AI:
Use TapHerd to list my devices. On the first one, open Settings, read the screen, tap Network & internet, and tell me what opened.Settings opens on the device, then Network & internet. Your AI tells you what it sees.
That's it. Your AI can now read the screen, tap, swipe, type, and open apps on your Android devices. See all 15 tools
Post a video optional
Once you're signed in to your own accounts on the device, your AI can post for you. TapHerd copies the video from your computer, gets the app ready, and cleans up afterwards.
- Put the video somewhere your AI can see, such as your project folder.
- Ask your AI something like:
Using TapHerd, copy launch.mp4 to my phone and post it to TikTok, Instagram Reels, and YouTube Shorts. Write a caption and tags for each. Keep the Short private. Delete the copy from the phone when you're done. - Watch it work. It uses
push_mediato copy the file,prepare_appto allow photo access and turn off camera and microphone prompts, then taps through each app, and finishes withremove_media.
Start with private or "Only you" visibility while you try it. App screens change often, so your AI checks each screen before tapping. Only post to accounts you own. Acceptable use
Add more phones optional
Free uses up to three devices at once. Start more emulators from Device Manager or plug in more phones, then:
tapherd devices # see what's connected
tapherd label emulator-5556 "Pixel 2" --group Creators
tapherd use emulator-5556 # pick which devices are activeThen ask your AI to work across a group, like “Open Settings on every phone in the Creators group.”
Running more than three phones? Pro is planned for 50+ devices, a dashboard, and scheduled posting.
See what's comingIf something's wrong
No device found
Make sure the emulator shows its home screen, then run adb devices -l. You should see emulator-5554 device.
unauthorized
Unlock the phone and accept Allow USB debugging. No prompt? Run adb kill-server, then adb devices.
offline
Run adb reconnect offline, or restart the emulator from Device Manager.
My AI doesn't see TapHerd
Check the file is valid JSON or TOML with no trailing commas, and fully restart the app. Claude Desktop must be quit, not just closed.
tapherd: command not found
Open a new terminal. Still missing? Run uv tool update-shell and open another one.
Emoji or accents don't type
Android's built-in typing is ASCII only. Install the free ADBKeyboard on the device. Steps
More fixes are in Troubleshooting. Still stuck? Open an issue with the output of tapherd doctor, and remove any account names first.