AgentTouch

https://github.com/wentong2022-arch/agenttouch
Admin
AgentTouch is an ESP32-S3 desk pet that displays AI coding agent states, allows one-tap action...
Tokens:28,181
Snippets:209
Trust Score:5.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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
```

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

### 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.
```

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

### 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
```

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

### 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
```

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

### 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"}
```

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

### 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
```
Tokens:
Raw