claude-code-eyes

claude-code-eyes

Give Claude Code eyes. A camera skill so Claude doesn't just read about your hardware — it sees it and drives the whole loop: write the firmware, flash the board, connect the API, look at the display, fix the UI, reflash — verifying its own work where it actually lives: on the glass.

Built by a quadriplegic dev who watched Claude Code wire up an ESP32 and fix its on-screen UI — by looking. This skill is how Claude sees.

Most of what Claude works with is text: code, logs, API responses. But some outputs live where no test can reach them — a font that silently drops characters, a wire in the wrong hole, a number clipped at the edge of an LCD. claude-code-eyes grabs the current camera frame so Claude can read it like any other file — then act on it: edit, reflash, and look again until the real thing is right.

🔍 New in v1.1 — Claude can zoom the lens. Too small to read? It zooms in and looks again instead of guessing, then puts the camera back where it found it. Chip markings, resistor bands, silkscreen, fine print.

Releases

See it in action

▶️ Watch the full 25-second demo — Claude drives the build from the laptop, the board runs the live countdown, and the phone (IP Webcam) is the eye Claude looks through.

🤯 What Claude Code pulled off here — from a prompt, my home Wi-Fi, and the API it would use, and with zero hardware help from me: it designed the board → relay → API architecture, wrote the ESP32 firmware and a Go relay service, flashed the board, shipped 5 clean OTA updates, wrote its own tests (and caught two of its own that were testing nothing) — and found and fixed a UI bug on the display that every green test missed, by looking at the panel through this camera. My whole job: set the goal, plug in the cable, press the button, aim the phone. Claude did the engineering.

---

Get a camera in 2 minutes (recommended: IP Webcam)

The primary, best-supported camera source is the IP Webcam Android app — it turns any spare Android phone into an HTTP snapshot camera.

1. Install it from Google Play: 👉 https://play.google.com/store/apps/details?id=com.pas.webcam
2. Open the app, scroll to the bottom, and tap Start server.
3. The app shows an address on screen, e.g. http://192.168.0.42:8080. That IP:port is your camera URL.
4. Point the phone at whatever you want Claude to see (a phone stand or a stack of books works). Set the config below to that URL.

export CCE_CAM_TYPE=ipwebcam
export CCE_CAM_URL=http://192.168.0.42:8080      # the IP:port the app shows
# optional, if you enabled "Login/password" in the app:
# export CCE_CAM_AUTH=user:pass

No Android phone? Any camera that can serve a still image over HTTP works — see Camera backends for a Raspberry Pi or a fully generic snapshot URL.

---

Install

The skill is a folder with a SKILL.md and a snap.sh. Put it where Claude Code looks for skills:

Personal (all your projects):

git clone https://github.com/fcavalcantirj/claude-code-eyes.git \
  ~/.claude/skills/claude-code-eyes

Project-scoped (shared with a repo):

git clone https://github.com/fcavalcantirj/claude-code-eyes.git \
  /path/to/your/project/.claude/skills/claude-code-eyes

Or just copy the skill's files into a claude-code-eyes/ folder under either skills/ location. That's the whole skill.

One-command setup

From the installed skill folder, run the setup helper — it writes your camera config and grabs a test frame, so there's nothing to hand-edit:

bash ~/.claude/skills/claude-code-eyes/setup.sh

It asks for your camera URL — or, if you leave it blank, scans your LAN for an IP Webcam and lets you pick one. Prefer non-interactive?

# writes the config and verifies it in one shot (add --auth user:pass if needed)
bash ~/.claude/skills/claude-code-eyes/setup.sh --url http://192.168.0.42:8080 --type ipwebcam

Other flags: --scan (just list IP Webcams on the LAN), --local (write ./.cce.env for this project instead of the global config), --show (where config lives). You can still set the env vars or edit the config by hand — see Configuration.

Then ask Claude to look:

"Are you seeing this? Is the yellow wire in G4?" "Look at the display — does it say ~1h23min in full?" "Watch this — I'm going to press the button."

---

What it's for

Visual-verify — catch what green tests cannot

A rendered screen is an output no unit test can see. Snap before and after a render change and diff the frames; check the frame against what the spec/API says the screen should show; report the mismatch. It has a small case library baked into the skill: font coverage / dropped characters, text-vs-graphic collisions, clipping at a panel edge, and stale-vs-live renders.

Zoom in — read what's too small to see

Claude drives the lens itself. When a marking, band, or line of text won't resolve, it zooms and takes another look rather than reporting a guess or "the image is too blurry":

bash snap.sh --zoom 5      # 5x, capture, then restore the previous zoom
bash snap.sh --focus       # soft rather than small? autofocus, then capture

--zoom is a plain magnification from 1 to 10, snapped to a step your camera actually supports, and the previous level is restored afterwards — so a zoomed look never silently changes what the next capture sees. Needs CCE_CAM_TYPE=ipwebcam; other backends say so and still capture. Full details ↓

Wiring-mentor — a second set of eyes before power-on

Ask Claude to check a build's wiring against its wiring table before you apply power: it calls out mismatches, verifies polarity and voltage rails (no 5 V on a 3.3 V-only pin), and — importantly — refuses to guess a pin it can't read, zooming in for a better look and asking you to aim the camera closer if that still isn't enough.

---

Camera backends

Selected with CCE_CAM_TYPE:

The url mode is the escape hatch: point it at any endpoint that returns a JPEG or PNG (a webcam server, an ESP32-CAM, a signed snapshot URL, ?action=snapshot, etc.). snap.sh verifies the response is actually an image (by magic bytes), so a web page served with 200 OK won't be mistaken for a photo.

# Raspberry Pi camera-streamer
export CCE_CAM_TYPE=camera-streamer
export CCE_CAM_URL=http://raspberrypi.local:8080

# Any snapshot URL
export CCE_CAM_TYPE=url
export CCE_CAM_URL=http://192.168.0.50/cam/snapshot.jpg

Experimental: local USB webcam (untested — verify it yourself)

If you have a USB/built-in webcam and ffmpeg installed, you can grab a single frame directly. This is not shipped as a snap.sh backend