### Install Pillow with setup script

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

If the build says Pillow is missing, run `host/setup.sh --pillow` to install it.

```bash
host/setup.sh --pillow
```

--------------------------------

### Hand over to seat setup

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Fetch the seat configuration guide from the host. This returns the seat setup documentation with a live section about the current Mac, which maps agents to the board's five seats.

```bash
curl -s http://127.0.0.1:8788/agent-setup
```

--------------------------------

### Clone repository and run setup script

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Clones the AgentTouch repository and runs the setup script. The --check flag reports what would change without applying. The setup script installs dependencies, a host app, a LaunchAgent, and hooks, and asks about Pillow.

```bash
git clone https://github.com/wentong2022-arch/agenttouch.git && cd agenttouch
host/setup.sh --check     # optional: report what it would change
host/setup.sh             # install; safe to re-run
```

--------------------------------

### Install AgentTouch on Mac and flash firmware

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/README.md

Commands to clone the repository, run the Mac-side setup script, and flash the firmware to the board using PlatformIO. Requires a Mac with Xcode command line tools and PlatformIO, and the board connected via USB.

```bash
git clone https://github.com/wentong2022-arch/agenttouch.git && cd agenttouch
host/setup.sh                                  # the Mac side; say yes to Pillow
cd firmware && pio run -e amoled216 -t upload  # first flash, board on USB
```

--------------------------------

### Run host setup with Pillow

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Installs the host with Pillow support, which is needed to bake Chinese glyphs from the system fonts. The </dev/null ensures it never prompts.

```bash
host/setup.sh --pillow </dev/null     # user agreed to Pillow
```

--------------------------------

### Install Pillow with pip

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

Alternative to the setup script: install Pillow 11.3.0 with `/usr/bin/python3 -m pip install --user pillow==11.3.0`.

```bash
/usr/bin/python3 -m pip install --user pillow==11.3.0
```

--------------------------------

### Turn on host with pet on

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

If `pet status` says OFF, run `pet on` to start the host.

```bash
pet on
```

--------------------------------

### Run host setup without Pillow

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Installs the host without Pillow. Pillow will then appear in the manual list of things to do later.

```bash
host/setup.sh </dev/null              # user declined Pillow (it then shows up in the manual list)
```

--------------------------------

### Re-run host setup script

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

Re-run `host/setup.sh` to fix firewall issues and re-add hooks. Check its output for errors.

```bash
host/setup.sh
```

--------------------------------

### Check host setup without changes

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Runs the setup script in check-only mode. It reports what would be changed and any failures, but makes no modifications.

```bash
host/setup.sh --check      # reports only, changes nothing
```

--------------------------------

### Install PlatformIO via Homebrew

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Installs PlatformIO using Homebrew. Use this if Homebrew is installed.

```bash
brew install platformio            # if Homebrew is installed
```

--------------------------------

### Example config.json with approve_keys, follow_front, stretch_after_min, pickup_page

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/03-usage.md

Shows a JSON configuration object for ~/.agentpet/config.json. The approve_keys maps the 'codex' action to the 'cmd+enter' key combination. Setting stretch_after_min to 0 disables the break reminder. After editing the file by hand, restart the host with 'pet restart'.

```json
{
  "approve_keys": {"codex": "cmd+enter"},
  "follow_front": false,
  "stretch_after_min": 0,
  "pickup_page": "follow"
}
```

--------------------------------

### Install PlatformIO via pip

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Installs PlatformIO using pip3 with the --user flag. The pio executable lands in the user base bin directory.

```bash
pip3 install --user platformio     # otherwise; pio lands in "$(/usr/bin/python3 -m site --user-base)/bin"
```

--------------------------------

### Check pet status and turn on

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Use `pet status` to check if the host is running. If it says OFF, use `pet on` to start it. Logs can be viewed with `tail -80 /tmp/agentpet_host.log`.

```bash
pet status
```

```bash
pet on
```

```bash
tail -80 /tmp/agentpet_host.log
```

--------------------------------

### Restart and check host with pet commands

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Restarts the host service and checks its status. Use after the setup script to verify the host is running correctly.

```bash
pet restart
pet status
```

--------------------------------

### Prompt for coding agent to install AgentTouch

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/README.md

A prompt to send to a coding agent (Claude Code, Codex, etc.) to install AgentTouch by following the provided guide. The agent will stop and ask for user input when needed, and will not type passwords or change system permissions.

```markdown
> Please install AgentTouch on this Mac by following https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md. Stop and tell me whenever you need my hands or a password.
```

--------------------------------

### Example protocol messages

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/05-architecture.md

Three example JSON messages showing the protocol format: a state update, a voice command, and a key press. Each line is a separate JSON object ending with a newline.

```json
{"t":"state","agents":{"claude":"working","codex":"needs_you","qoder":"off","qoderwork":"off","forest":"idle"}}
{"t":"voice","a":"start","agent":"claude","mic":false,"link":"ble"}
{"t":"key","k":"approve"}
```

--------------------------------

### Build firmware and trigger OTA update with curl

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/05-architecture.md

Builds the firmware with PlatformIO, copies it to the host's staging directory, then triggers an OTA update via curl. The first curl command performs a normal update (~50 s end to end), while the second with ?rollback=1 reverts to the previous firmware. The host pushes fw.bin to /agentpet/fw/new.bin; the board checks size and CRC32, writes the other app slot, boots from it, and says 'hello' again.

```bash
cd firmware && pio run -e amoled216 && cp .pio/build/amoled216/firmware.bin ~/.agentpet/fw.bin
curl -s http://127.0.0.1:8788/ota              # about 50 s end to end
curl -s "http://127.0.0.1:8788/ota?rollback=1"  # back to the previous firmware
```

--------------------------------

### Development commands: test, build, run, and check state

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/05-architecture.md

Commands for running host unit tests, building firmware, deploying host changes, and checking the host state via HTTP.

```bash
/usr/bin/python3 host/test_host.py -v            # host unit tests: stdlib only, no board, no network
cd firmware && pio run -e amoled216               # build; add -t upload to flash over USB
cp host/agentpet_host.py host/almanac_bank.json ~/.agentpet/ && pet restart   # run your host changes
curl -s http://127.0.0.1:8788/state               # host, links, card, firmware
```

--------------------------------

### Flash firmware with PlatformIO (pio run -e amoled216 -t upload)

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Run from the firmware directory to compile and upload the firmware to the board. The first build downloads the ESP32 toolchain and libraries, taking several minutes. It also bakes firmware/src/almanac_font.h from system fonts. If no port is found, hold the left key (BOOT) while plugging in the cable.

```bash
cd firmware
pio run -e amoled216 -t upload
```

--------------------------------

### Update firmware over Wi-Fi

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Builds the firmware, copies the binary to the agentpet directory, and triggers an OTA update over Wi-Fi. Takes about 50 seconds.

```bash
pio run -e amoled216 && cp .pio/build/amoled216/firmware.bin ~/.agentpet/fw.bin && curl -s http://127.0.0.1:8788/ota
```

--------------------------------

### Clone the AgentTouch repository

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Clones the repository into ~/agenttouch and changes into that directory. Use this if the current directory does not already contain host/setup.sh.

```bash
git clone https://github.com/wentong2022-arch/agenttouch.git ~/agenttouch && cd ~/agenttouch
```

--------------------------------

### Claim the board with pet claim

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

If the board is following another Mac, run `pet claim` and then tap 连接 (Connect) on the board.

```bash
pet claim
```

--------------------------------

### Check front app with curl test/front

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

Use `curl -s http://127.0.0.1:8788/test/front` to see which app the host thinks is in front and which one it would raise.

```bash
curl -s http://127.0.0.1:8788/test/front
```

--------------------------------

### Verify host and board status

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Run these commands to verify the host is running, the board is connected via Bluetooth and Wi-Fi, and the fonts have been pushed successfully. The 'pet status' command shows host status, while the curl commands check the state and font status endpoints.

```bash
pet status                                   # host running, product=s3, ble=True, tcp=1
```

```bash
curl -s http://127.0.0.1:8788/state          # "ble": true (Bluetooth), "boards": 1 (Wi-Fi), "sd": {"mb": card size}
```

```bash
curl -s http://127.0.0.1:8788/fonts/status   # "state": "ok"
```

--------------------------------

### Flash firmware over USB

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Builds and uploads the firmware to the board over USB. The first build downloads the ESP32 toolchain and libraries, which can take several minutes.

```bash
cd firmware && pio run -e amoled216 -t upload
```

--------------------------------

### View host log with pet log

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

The log is at `/tmp/agentpet_host.log`; use `pet log` to view it.

```bash
pet log
```

--------------------------------

### Check host status with pet status

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

Use `pet status` to check whether the host is running and how the board is connected. This is the first step in troubleshooting.

```bash
pet status
```

--------------------------------

### Restart host after granting Bluetooth permission

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

After adding the Bluetooth permission for AgentPetHost.app, run `pet restart` to apply the change.

```bash
pet restart
```

--------------------------------

### Update firmware over Wi-Fi with pio run and curl OTA

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Build the firmware for the amoled216 environment, copy the binary to ~/.agentpet/fw.bin, then trigger an OTA update via the /ota endpoint. The board flashes its other app slot and restarts, taking about 50 seconds. Use the rollback parameter to revert to the previous version.

```bash
cd firmware && pio run -e amoled216 && cp .pio/build/amoled216/firmware.bin ~/.agentpet/fw.bin
curl -s http://127.0.0.1:8788/ota
curl -s "http://127.0.0.1:8788/ota?rollback=1"   # back to the previous version
```

--------------------------------

### Check status and state with pet status and curl

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Verify the host is running and the board is connected. The curl command queries the local state endpoint and expects a JSON response with "ble": true, "boards": 1, and an "sd" object.

```bash
pet status                                   # host running, board connected
curl -s http://127.0.0.1:8788/state          # "ble": true, "boards": 1, "sd": {...}
```

--------------------------------

### Check USB modem devices

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

List USB modem devices to diagnose upload failures or missing ports. Use `ls /dev/cu.usbmodem*`.

```bash
ls /dev/cu.usbmodem*
```

--------------------------------

### List sessions with curl test/sess/list

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

Use `curl -s http://127.0.0.1:8788/test/sess/list` to list the sessions the host sees and how it reaches each tab.

```bash
curl -s http://127.0.0.1:8788/test/sess/list
```

--------------------------------

### Rollback firmware with curl OTA

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/04-troubleshooting.md

If a cable-free update went wrong, use `curl -s "http://127.0.0.1:8788/ota?rollback=1"` to go back to the previous firmware.

```bash
curl -s "http://127.0.0.1:8788/ota?rollback=1"
```

--------------------------------

### Flash factory firmware with esptool

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Writes the factory firmware image to the device from address 0x0. The command uses a wildcard for the serial port and the specific firmware file name.

```bash
esptool --port /dev/cu.usbmodem* write-flash 0x0 ESP32-S3-Touch-AMOLED-2.16-FactoryOnly-260318.bin
```

--------------------------------

### Claude Code hooks configuration in ~/.claude/settings.json

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/05-architecture.md

Hooks in ~/.claude/settings.json POST each event to http://127.0.0.1:8788/hook/claude/<Event>?src=agentpet. They use `curl -m 2 … || true` so a missing host never blocks Claude Code. The hooks map events to states: UserPromptSubmit, PreToolUse, PostToolUse set working; Notification sets needs_you (except the idle reminder); Stop sets done; SessionStart/SessionEnd add/remove sessions.

```json
{"hooks": {"PermissionRequest": [{"hooks": [{"type": "command",
  "command": "/Users/<you>/.agentpet/codex_permission_hook.sh",
  "timeout": 5, "statusMessage": "AgentTouch needs_you"}]}]}}
```

--------------------------------

### Stop host and remove Claude Code hooks

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Stop the host process with 'pet off' (it restarts at the next login) and remove the Claude Code hooks using the provided Python script.

```bash
pet off                                  # stop the host (it starts again at the next login)
/usr/bin/python3 host/install_hooks.py --remove   # remove the Claude Code hooks
```

--------------------------------

### Check and push card fonts via HTTP API

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/doc/02-install.md

Use curl to check font status or force a rebake and push of all four font files. The push command rebakes and pushes all four fonts, which can take about 5 minutes for 16 MB. The glyphs come from macOS's Songti, Hiragino Sans GB, and Menlo.

```bash
curl -s http://127.0.0.1:8788/fonts/status
curl -s "http://127.0.0.1:8788/fonts/push?force=1"   # rebake and push all four
```

--------------------------------

### Check font baking status

Source: https://github.com/wentong2022-arch/agenttouch/blob/main/host/agent_install.md

Poll the font baking status endpoint. The response contains a 'state' field with values like 'wait', 'nocard', 'nopil', 'baking', 'pushing', 'ok', or 'error'. Use this to monitor the automatic font baking and pushing process.

```bash
curl -s http://127.0.0.1:8788/fonts/status
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.