reterminal

Agent and CLI for operating Seeed Studio reTerminal edge devices — the reTerminal E (LAN, ESPHome push) and the reTerminal Sticky (ESPHome, an always-on board service on the reterminal domain, enrolled-service push, PDF pagination, and a touch dashboard that drives an AC through Sensibo) — provisioning, display, and I/O for both.

What you get

• Device operation — map devices to serial ports, query and flash SenseCraft firmware, render to the e-paper display, and sound the buzzer, all from the CLI.
• The Sticky as a first-class device — flash it via firmware, then run reterminal board serve: enrolled services push content over HTTP, PDFs page-turn by touch, and a touch dashboard drives an air conditioner through Sensibo, all authenticated end to end and reachable off-LAN through a cloudflared tunnel the board tunnel verbs wrap. See docs/esphome-reterminal-sticky.md and docs/delivery-map.md.
• An agent-first CLI cited from teken (afi-cli) — every command also speaks --json, and the runtime package has no third-party dependencies.
• A mesh identity — culture.yaml (suffix + backend) and the matching prompt file (CLAUDE.md for backend: claude).
• The canonical guildmaster skill kit (11 skills) under .claude/skills/, vendored cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.

Quickstart

uv sync
uv run reterminal learn               # what the tool does + the command map (add --json)
uv run reterminal devices list        # local: device→serial-port mappings on this machine
uv run reterminal display set "hello" # needs a reachable reTerminal E (ESPHome firmware)
uv run reterminal whoami              # identity from culture.yaml
uv run pytest -n auto                 # run the test suite

# the board service (reTerminal Sticky, or E1001 enrolled as a panel):
uv run reterminal board serve --port 0     # foreground; --state-dir for a fixed home
uv run reterminal board token issue myservice --kind service
uv run reterminal board panel add sticky-1 --panel-profile sticky
uv run reterminal board push card --title "hello" --panels sticky-1

# the three demos (self-hosted by default — no hardware needed to run them):
bash scripts/demos/demo-1-service-push.sh
bash scripts/demos/demo-2-pdf-reader.sh
bash scripts/demos/demo-3-ac-dashboard.sh

devices is local; firmware, display, and speaker act on a connected reTerminal E over LAN (USB-serial for firmware flash, the ESPHome HTTP API for display / speaker). board is the Sticky/E1001 delivery service: it runs independently of a connected device and talks to enrolled panels over HTTP, device-initiated (the panel polls the board, not the reverse) — see docs/esphome-reterminal-sticky.md for the full delivery contract and docs/esphome-reterminal-e1001.md for the E1001's LAN-push config.

CLI

Operate a reTerminal E over LAN:

Run the board service (Sticky and/or E1001 as enrolled panels):

Every board endpoint requires a bearer token, /health included — see reterminal explain board. Demo scripts + fixtures live under scripts/demos/: demo-1-service-push.sh, demo-2-pdf-reader.sh, demo-3-ac-dashboard.sh each self-host a board and print MEASURED: timings against the spec's battery-first targets, or (with BOARD_URL/PANEL_ID/PANEL_TOKEN/SERVICE_TOKEN set) run the same script against real hardware.

Introspection and identity:

Every command supports --json. Each noun group has its own overview (reterminal display overview). Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Fork it for another agent

reterminal began as the culture-agent-template scaffold, so it doubles as a starting point for a new AgentCulture mesh agent. To repurpose it:

1. Rename the package reterminal/ and the reterminal CLI/dist name throughout pyproject.toml, the package, tests/, sonar-project.properties, and this README.md. The name is hard-coded in ~100 places, so list every occurrence first — see the git grep discovery command in CLAUDE.md, the authoritative rename procedure.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, deploy setup).

License

MIT — see LICENSE.