Install guide

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
Your computer:
1

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)

  1. Download Android Studio from developer.android.com/studio and install it.
  2. Open it and choose the Standard setup. It downloads the emulator and adb.
  3. Open More Actions → Virtual Device Manager, then + → Create Virtual Device.
  4. 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.
  5. Press Play and wait for the home screen.

Option B: your own Android phone

  1. Open Settings → About phone and tap Build number seven times.
  2. Open Settings → System → Developer options and turn on USB debugging.
  3. Connect it with a data cable. Some cables only charge.
  4. Unlock the phone and accept Allow USB debugging. Tick Always allow.

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.

2

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 | sh

The 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.
  • Installs TapHerd and runs tapherd doctor.
Prefer to install by hand?

Install uv, then:

uv tool install tapherd
tapherd doctor

If 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.

3

Check everything 30 sec

With the emulator or phone on, run:

tapherd doctor

You 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.

4

Connect your AI 2 min

TapHerd prints the exact settings for your AI app, then tells you where to paste them. Pick your app:

  1. In your project folder, save the settings as .mcp.json:
    tapherd config mcp --client claude-code > .mcp.json
  2. Start claude in that folder and approve the tapherd server when asked.
  3. Type /mcp to check it shows as connected.

Always paste what your tapherd config mcp prints. It points at the Python and adb on your computer. All details

5

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

6

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.

  1. Put the video somewhere your AI can see, such as your project folder.
  2. 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.
  3. Watch it work. It uses push_media to copy the file, prepare_app to allow photo access and turn off camera and microphone prompts, then taps through each app, and finishes with remove_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

7

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 active

Then 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 coming
?

If 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.