What is clawdometer-eink AGENTS.md?

A set of coding instructions for clawdometer-eink, a project that displays Claude usage and live coding-agent status on an ESP32-S3 e-paper device. It covers its C++ firmware, Python daemon, and Python hook.

Use it when building, flashing, testing, or changing the firmware, macOS daemon, hooks, or their communication protocol.

It records the project’s architecture and required checks so changes continue to work across the device, computer, Bluetooth connection, and status hook.

clawdometer-eink AGENTS.md — Instructions file by nsyll

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/nsyll/clawdometer-eink/agents-md

Clone the repo

git clone --depth 1 https://github.com/nsyll/clawdometer-eink

Made for: Codex, OpenCode.

Per session 1,173 This file is loaded in full into every session.

When invoked 1,173 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.01173	$0.01173
Opus 5	$0.00587	$0.00587
Sonnet 5	$0.00235	$0.00235
Haiku 4.5	$0.00117	$0.00117

Measured 2d ago against content hash c09e95ef229e, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

clawdometer-eink AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

Origin

Copies of this mod

1 near-identical copy found in the catalogue:

clawdometer-eink CLAUDE.md — 100% identical, 0 lines differ

AGENTS.md · 61 lines

How it starts

The opening of the file, as written. The whole thing — 61 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Clawdometer — guide for AI coding agents

Read this before touching code. It encodes the hard-won gotchas; violating them produces firmware that compiles fine and then fails silently on the desk.

What this is

An ESP32-S3 e-paper gadget showing Claude usage + Claude Code live status. Three parts: firmware/ (PlatformIO, Arduino, C++) · daemon/ (single-file Python, bleak+httpx, macOS-first) · hooks/ (Claude Code hook, stdlib-only Python). Interfaces between them are specced in docs/PROTOCOL.md; component responsibilities in docs/ARCHITECTURE.md.

Build / run / test

# firmware
cd firmware && pio run                 # compile (always do this before claiming success)
./flash.sh                             # upload over USB — auto-picks the real serial port
pio device monitor                     # 115200 baud serial logs

# daemon (needs a real macOS Terminal for Bluetooth permission)
cd daemon && python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
./.venv/bin/python claude_usage_daemon.py          # live dashboard
./.venv/bin/python claude_usage_daemon.py --plain  # line logs

# hook (test standalone; must ALWAYS exit 0)
echo '{"hook_event_name":"Stop","transcript_path":"<some.jsonl>"}' | python3 hooks/cc_status_hook.py
cat ~/.clawd/cc_status.json

There is no automated test suite. Verify firmware changes by compiling; verify daemon logic by importing the module and calling functions directly (it's import-safe); verify the hook with synthetic stdin payloads as above.

Hardware gotchas (the expensive lessons)

EPD_PWR (GPIO6) is ACTIVE-LOW. LOW = panel powered. Get this backwards and the screen is just blank with no error.
ES8311 codec needs MCLK before I2C. I2S must be started before es8311_init, or the codec never ACKs. I2S clocks are stopped between chimes for power — playMelody restarts them.
SPI pins must be remapped after display.init() (see Display.cpp); the reverse order breaks the panel on this board.
Deep sleep releases GPIO pads. VBAT_HOLD (GPIO17) keeps the battery latch closed — it MUST be gpio_hold_en'd before esp_deep_sleep_start() or the board powers itself off and won't wake. Same technique holds the panel/audio rails off.
BLE payload > default MTU. The JSON is ~450 B; the device sets MTU 512. If you grow the payload past ~500 B, writes fail silently — shrink field names or split.
NimBLE-Arduino must stay 1.4.x while the platform is Arduino-ESP32 2.0.x (PlatformIO espressif32). 2.x NimBLE needs a newer core.

Read the full file on GitHub · 61 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

2d ago First seen · 61 lines · 1,173 tokens per session scan A c09e95ef229e

Subscribe to this mod's changes

clawdometer-eink AGENTS.md is an instructions file published in the GitHub repository nsyll/clawdometer-eink (5 stars, last pushed 9d ago), licensed MIT. It adds 1,173 tokens to every session, about $0.0059 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Hardware and IoT anthropic ble claude claude-code desk-gadget e-ink

edge AGENTS.md

Instructions for OpenStrap/edge, covering agents.md — openstrap edge, 1. what this is, 3. hard invariants — violating these is a p0 regression, 4. recurring bug patterns — what actually ships broken here and 4.3 sticky boolean latches never reset on the failure path.

OpenStrap/edge · 4,019 tokens

blea AGENTS.md

Instructions for Nitmi/blea, a project described as: Universal Agent Plugin for safe BLE diagnostics and automation, with Agent Plugins 1.0.0 metadata, a portable Skill, deterministic CLI, local MCP, and evidence capture/diff/replay.

Nitmi/blea · 247 tokens

platform-nordicnrf54 AGENTS.md

Instructions for caveman99/platform-nordicnrf54, covering agent guide for this repo, what this repo is, companion repos, project conventions and commit messages.

caveman99/platform-nordicnrf54 · 1,812 tokens

FastLED GEMINI.md

Gemini CLI instructions for FastLED/FastLED, a project described as: The FastLED library for colored LED animation on Arduino. Please direct questions/requests for help to the FastLED Reddit community: http://fastled.io/r We'd like to use github "issues" just for tracking library bugs / enhancements.

FastLED/FastLED · 9 tokens

kicad-happy GEMINI.md

Instructions for aklofas/kicad-happy, covering kicad-happy, agent guidelines, skills, running analysis and schematic analysis.

aklofas/kicad-happy · 1,207 tokens

brilliant_sdk AGENTS.md

Instructions for brilliantlabsAR/brilliant_sdk, covering brilliant sdk — agent guide, how an app works (the pattern behind everything), minimal reading paths, verify without hardware and testing.

brilliantlabsAR/brilliant_sdk · 1,817 tokens