⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
claude-code-eyes
Look at real hardware, screens, panels, and wiring on a desk or workbench through a camera, so Claude can SEE physical output that no unit test, log, or API can. Use whenever the user says "are you seeing this?", "olha isso", "look at this", "watch this", "can you see...", "check the camera", "look at the screen" / "look at the display", "is this wired right?", or "what's this part?"; asks to visually verify a rendered display, LCD, LED, or panel; wants a wiring, polarity, or voltage-rail check
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
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
| Version | |
|---|---|
| v1.1.1 | LAN cameras bypass the proxy |
| v1.1.0 | Claude can zoom the lens |
| v1.0.0 | First public release — Claude sees through your camera |
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.
- Install it from Google Play: 👉 https://play.google.com/store/apps/details?id=com.pas.webcam
- Open the app, scroll to the bottom, and tap Start server.
- The app shows an address on screen, e.g.
http://192.168.0.42:8080. ThatIP:portis your camera URL. - 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
~1h23minin 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:
CCE_CAM_TYPE | Source | Request |
|---|---|---|
ipwebcam | Android IP Webcam app | GET $CCE_CAM_URL/shot.jpg |
camera-streamer | Raspberry Pi camera-streamer | GET $CCE_CAM_URL/snapshot |
url (default) | Anything that returns a still image over HTTP | GET $CCE_CAM_URL (verbatim) |
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
// HOW IT'S BUILT
// FILES
16 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
SKILL.md7.9 KBe8ccea585cccupstream ↗
--- name: claude-code-eyes description: Look at real hardware, screens, panels, and wiring on a desk or workbench through a camera, so Claude can SEE physical output that no unit test, log, or API can. Use whenever the user says "are you seeing this?", "olha isso", "look at this", "watch this", "can you see...", "check the camera", "look at the screen" / "look at the display", "is this wired right?", or "what's this part?"; asks to visually verify a rendered display, LCD, LED, or panel; wants a wiring, polarity, or voltage-rail check before power-on; or needs to confirm a font, layout, clipping, or on-screen value renders correctly instead of trusting green tests. Grabs the current camera frame(s) and reads them; supports a watch mode for an action in progress. Needs a snapshot-capable camera reachable over HTTP (Android IP Webcam app, Raspberry Pi camera-streamer, or any snapshot URL) set via CCE_CAM_URL. --- # claude-code-eyes — let Claude look at the real world Some outputs live where no test, log, or API can reach them: a display panel, an LED, a breadboard, a rack of wires. This skill grabs the current camera frame and lets you `Read` it, so you answer from what you actually see — not from what the code *should* produce. ## How 1. Run: `bash <path-to-skill>/snap.sh` — it prints the path(s) of the captured JPEG/PNG. (It works from any directory.) 2. `Read` each printed path — the Read tool renders images visually. 3. Answer from the frame. Reference positions concretely: "the red wire on the left rail, third hole down", not "a wire near the top". If a capture fails, read the error before retrying — it names the actual cause and the fix. One case is worth knowing: Claude Code runs Bash in a sandbox that blocks LAN addresses, so a camera your own terminal reaches fine can be unreachable here. `snap.sh` detects that and prints the fix already filled in — either approve Claude's offer to rerun the command outside the sandbox, or add the printed `sandbox.excludedCommands` entry to `~/.claude/settings.json` (the network allowlist does *not* cover private addresses). Frames are written under `./.claude-code-eyes/` in the working directory, not `$TMPDIR`, because sandboxed commands and the Read tool resolve `$TMPDIR` differently. See the README's Troubleshooting section. **When you cannot read something, zoom instead of guessing.** If a label, marking, or band is too small to resolve, do not report a guess and do not say the image is too blurry — take another look: ```bash bash <path-to-skill>/snap.sh --zoom 5 # then Read the new frame bash <path-to-skill>/snap.sh --focus # if it is soft rather than small ``` `--zoom` is a magnification from 1 to 10 and the previous zoom is restored afterwards, so it is safe to reach for. Requires `CCE_CAM_TYPE=ipwebcam`; other backends say so and still capture. Escalate deliberately: 1x to frame the scene, then zoom to read the detail you actually need. For **"watch this"** / an action in progress: `bash <path-to-skill>/snap.sh 3 2` (3 frames, 2 s apart), then compare the frames and narrate what changed. Longer processes: raise the count/interval. ## Visual-verify: catch what green tests cannot A rendered screen is an output no unit test can see. This is the use case that makes this more than a webcam grab. **Workflow for any display/render change:** 1. **Before/after** — snap once before the change, once after, and diff the two frames. 2. **Against the source of truth** — take what the spec / API / expected string says the screen *should* show, and check the frame against it character by character, element by element. 3. **Report mismatches** — say exactly what differs, where. **A small case library** (real bugs that every automated layer passed): - **Font coverage / silently-dropped characters.** A 48 px clock font contained only `0-9 : . - a p m`; handed `~1h23min` it rendered **`1 24m`** — `~ h i n` were dropped *silently*. The bytes were valid ASCII and the test asserting ASCII passed; the narrow thing was the *font*. Only the camera caught it. - **Text ↔ graphic collision.** With the text finally rendering in full, the tail of a number was drawn *underneath* a status icon sharing that row. It had already been misread as a pass once — look at the whole frame, not just the part you expected to change. - **Clipping at a panel edge.** Text that runs past the usable width is truncated by the panel, not by your string — you only see it on the glass. - **Stale vs live.** A frozen render can look identical to a live one. Confirm the screen reflects *now* (a value you just changed, a timestamp, a known-stale state that should read "offline"/grey rather than a frozen number). Rule of thumb: **any change to a render path or a font is not "done" until a frame confirms it.** ## Wiring-mentor: before you approve a power-on When the question is "should I connect that?" / "is this right?", the frame is checked against a plan, not eyeballed: - **Check the frame against the build's wiring table** (the from-pin → to-pin contract). Call out **every** mismatch. - **Wire-color discipline** helps a photo be checked against a plan (e.g. red = 3V3/5V, black = GND, other colors per signal). - **Verify polarity and voltage rails before saying "power it on":** no 5 V on a 3.3 V-only pin (many MCU GPIOs, e.g. ESP32, are NOT 5 V-tolerant); check battery / JST polarity (reversed connectors are a classic release-the-smoke gotcha). - **Safety rails:** a relay/module switching **mains** → stop and involve a qualified human. Don't hot-plug camera ribbons or delicate connectors. - **Too far or too blurry to read pin labels? SAY SO and ask for a closer aim.** Never guess a pin you cannot read. ## Know what your instrument can and cannot see The camera is an instrument, and so is every other tool you trust. A blank result is **not** a negative result until the instrument itself is proven working. Three ways the same lesson bit in one session: - **A tool that was never installed.** `tcpdump` returned empty because it wasn't on the box, and `2>/dev/null` turned "command not found" into a convincing clean capture — which became a confident, wrong root cause that had to be retracted. - **A log for a code path that logged nothing.** Silence from a serial log read as "it didn't happen" when the path simply emitted no line. - **A correct behavior invisible in the data.** A correct de-duplication leaves the database byte-identical to "nothing happened" — the only evidence was on the device and in the response, not in the store. So: when a frame looks blank, empty, or unchanged, first ask whether the camera is actually pointed, focused, and capturing — prove the instrument before you trust its silence. ## Config Set a camera endpoint (highest precedence first): exported env vars, then a `.cce.env` in the current directory, then `${XDG_CONFIG_HOME:-$HOME/.config}/claude-code-eyes/config`. Config files only fill values you haven't already exported; they are read, never executed. | Key | Meaning | |---|---| | `CCE_CAM_URL` | Camera URL (interpreted per `CCE_CAM_TYPE`) | | `CCE_CAM_AUTH` | Optional HTTP basic auth `user:pass` | | `CCE_CAM_TYPE` | `ipwebcam` \| `camera-streamer` \| `url` (default `url`) | Backends: - `ipwebcam` — Android **IP Webcam** app: `GET $CCE_CAM_URL/shot.jpg`. - `camera-streamer` — Raspberry Pi camera-streamer: `GET $CCE_CAM_URL/snapshot`. - `url` — **generic**: `GET $CCE_CAM_URL` exactly as given (any snapshot URL). A local USB-webcam grab via `ffmpeg` is possible but **experimental / untested** (it needs camera permission granted to your terminal); see the README. The supported, portable path is a snapshot URL via one of the backends above. ## Troubleshooting If nothing is reachable, `snap.sh` prints exactly which type + URL it tried. Common causes: the phone app or Pi server isn't running, the IP or port changed, HTTP basic auth is required (set `CCE_CAM_AUTH`), or you're not on the same network.README.md20 KB838db3c79f47upstream ↗
<p align="center"> <img src="banner.svg" alt="claude-code-eyes — give Claude Code eyes for the real world" width="100%"> </p> # 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](#zoom-in--read-whats-too-small-to-see).** 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 | Version | | |---|---| | **[v1.1.1](https://github.com/fcavalcantirj/claude-code-eyes/releases/tag/v1.1.1)** | LAN cameras bypass the proxy | | **[v1.1.0](https://github.com/fcavalcantirj/claude-code-eyes/releases/tag/v1.1.0)** | Claude can zoom the lens | | **[v1.0.0](https://github.com/fcavalcantirj/claude-code-eyes/releases/tag/v1.0.0)** | First public release — Claude sees through your camera | ## See it in action <p align="center"> <img src="demo.gif" alt="Claude Code flashing an ESP32 and fixing its on-screen UI, verified live through the camera" width="360"> </p> ▶️ **[Watch the full 25-second demo](https://drive.google.com/file/d/1z-ocjd7T9SdrBK2IVM4ku4vXrFHbrH6i/view)** — 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. ```bash 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](#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):** ```bash git clone https://github.com/fcavalcantirj/claude-code-eyes.git \ ~/.claude/skills/claude-code-eyes ``` **Project-scoped (shared with a repo):** ```bash 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 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? ```bash # 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](#configuration--precedence). 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 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 ↓](#zoom-and-focus) ### 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`: | `CCE_CAM_TYPE` | Source | Request | |---|---|---| | `ipwebcam` | Android **IP Webcam** app | `GET $CCE_CAM_URL/shot.jpg` | | `camera-streamer` | Raspberry Pi [camera-streamer](https://github.com/ayufan/camera-streamer) | `GET $CCE_CAM_URL/snapshot` | | `url` *(default)* | **Anything** that returns a still image over HTTP | `GET $CCE_CAM_URL` (verbatim) | 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. ```bash # 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** because it can't be tested in an automated/headless environment (macOS in particular blocks camera access behind an interactive permission prompt). The portable, supported path is a snapshot URL via one of the backends above. If you want to wire a local camera in yourself, these are the one-liners: ```bash # macOS (avfoundation) — index 0 is usually the built-in camera ffmpeg -y -loglevel error -f avfoundation -framerate 30 -i "0:none" -frames:v 1 out.jpg # Linux (v4l2) ffmpeg -y -loglevel error -f v4l2 -i /dev/video0 -frames:v 1 out.jpg ``` Grant your terminal camera permission first, run it manually, and confirm `out.jpg` is a real image before trusting it. --- ## Configuration & precedence Set config however you like — `snap.sh` resolves it in this order (first wins): 1. **Environment variables** already exported in your shell. 2. **`./.cce.env`** in the current working directory. 3. **`${XDG_CONFIG_HOME:-$HOME/.config}/claude-code-eyes/config`**. Config files only *fill in* values you haven't already exported, and they are **read, never executed** (`snap.sh` parses `KEY=VALUE` for a fixed allowlist of keys — a config file cannot run code or set anything else). Example `.cce.env`: ```ini CCE_CAM_TYPE=ipwebcam CCE_CAM_URL=http://192.168.0.42:8080 # CCE_CAM_AUTH=user:pass ``` | Key | Meaning | |---|---| | `CCE_CAM_URL` | Camera URL (interpreted per `CCE_CAM_TYPE`) | | `CCE_CAM_AUTH` | Optional HTTP basic auth `user:pass` | | `CCE_CAM_TYPE` | `ipwebcam` \| `camera-streamer` \| `url` (default `url`) | | `CCE_OUT_DIR` | Where frames are written (default `./.claude-code-eyes`) | ### Zoom and focus When you can't read a silkscreen label, a resistor band, or a chip marking, zoom in and look again instead of guessing: ```bash bash snap.sh --zoom 4 # 4x, capture, then restore the previous zoom bash snap.sh --focus # trigger autofocus, then capture bash snap.sh --zoom 6 3 2 # 6x + watch mode: 3 frames, 2s apart ``` `--zoom` takes a **magnification from 1 to 10**, not raw device units, and snaps to the nearest step the camera actually supports. The previous zoom is **restored after the capture** (including on Ctrl-C), so a zoomed shot never silently changes what the next one sees. Needs `CCE_CAM_TYPE=ipwebcam`. Other backends say so and still capture the frame. | Backend | Snapshot | Zoom | Focus | |---|---|---|---| | `ipwebcam` | yes | **yes** | **yes** | | `camera-streamer` | yes | no | no | | `url` | yes | no | no | <details> <summary>How it works on the device — verified 2026-08-20, and two traps</summary> | Purpose | Endpoint | Notes | |---|---|---| | Set zoom | `/settings/zoom?set=V` | **absolute**; V must be an allowed step, `100`=1x … `1000`=max | | Set zoom | `/ptz?zoom=P` | **percent 0–100** of the range — *not* an absolute value | | Focus | `/focus`, `/nofocus` | momentary trigger; `focusmode` is unchanged | | Capabilities | `/status.json?show_avail=1` | the device's own allowed zoom steps | Success is signalled by the response **body containing `Ok`** — the status code is `200` either way, so checking the code alone is not enough. **Trap 1: `/ptz?zoom=` is a percentage.** `/ptz?zoom=200` does not mean 2x — it clamps to maximum zoom. This skill uses `/settings/zoom?set=` instead. **Trap 2: `curvals.zoom` lags several seconds** behind a change. Code that reads it straight back sees the *old* value, so restoring from an immediate read restores the wrong level. `snap.sh` polls until the value settles. Note: `pydroid-ipcam` documents zoom as `/settings/ptz?zoom=N`; that path returns **404** on the device tested here. </details> ### Watch mode ```bash bash snap.sh 3 2 # 3 frames, 2 seconds apart — for "watch this" ``` Captured frames are written under `./.claude-code-eyes/` (override with `CCE_OUT_DIR`) and their paths are printed one per line. They land in the working directory, not `$TMPDIR`, on purpose — see the sandbox note below. --- ## Troubleshooting: the camera stopped working after a Claude Code update Claude Code runs Bash commands inside a [sandbox](https://code.claude.com/docs/en/sandboxing). It changed two things this skill depends on. Both are handled as of the current version, but if you are on an older copy — or you see the symptoms below — this is why. ### 1. The sandbox blocks your camera's address **Symptom:** Claude reports the camera as unreachable, but the exact same `curl` works in your own terminal. The sandbox pre-allows **no** network destinations. How it blocks depends on the address, and the two cases need *different* fixes (measured on Claude Code 2.1.236): | Camera address | How it's blocked | Fix | |---|---|---| | Private / LAN (`192.168.x`, `10.x`, `172.16-31.x`, `localhost`, `*.local`) | Below the proxy — the connection just fails, with no HTTP status | `sandbox.excludedCommands` | | Public host or public IP | The proxy answers `403` | `sandbox.network.allowedDomains` | **Almost every camera is on your LAN**, so this is usually the one you want. The quickest unblock needs no config at all: when the capture fails under the sandbox, Claude offers to **rerun the command outside the sandbox** — approve that and the frame is captured. For a permanent fix, exclude the capture command so the sandbox stays on for everything else: ```json { "sandbox": { "excludedCommands": ["bash /Users/me/.claude/skills/claude-code-eyes/snap.sh"] } } ``` Use **your** path — `snap.sh` prints the exact line for you on failure, already filled in. It must be the path you actually invoke, because entries are matched exactly or by prefix, never fuzzily: ```js prefix: cmd === entry || cmd.startsWith(entry + " ") exact: cmd === entry ``` A bare `"bash snap.sh"` therefore never matches `bash /path/to/snap.sh`. As a prefix, the absolute entry also covers watch mode (`snap.sh 3 2`). `sandbox.network.allowedDomains` does **not** work for a LAN camera: private ranges are rejected from the domain lists, which require public domain names. For a camera on a public host, it is the right fix: ```json { "sandbox": { "network": { "allowedDomains": ["cam.example.com"] } } } ``` IPs must be listed exactly — wildcards never match an IP. Put either in `~/.claude/settings.json` and restart Claude Code. `setup.sh` prints the correct one for your camera, and `snap.sh` prints it on failure. Run `/sandbox` to inspect the active policy. > A blocked LAN camera and a sleeping camera look **identical** at the network > layer — both are just a failed connection. `snap.sh` will not claim the sandbox > is at fault when it cannot tell; it reports the connection failure and notes the > sandbox as a possibility. The deciding test: if your own terminal can reach the > camera and Claude cannot, it is the sandbox. ### 1b. `set: pipefail: invalid option name` — CRLF line endings **Symptom:** it fails instantly, before ever touching the camera: ``` snap.sh: line 29: $'\r': command not found snap.sh: line 30: set: pipefail: invalid option name ``` The script has Windows (CRLF) line endings and bash chokes on the carriage returns. `git config core.autocrlf` defaults to `true` on Windows, so a clone can introduce this on its own — as can saving the file from a Windows editor. `snap.sh` cannot warn you about this itself: bash is already dead. `setup.sh` checks for it and says so. To fix a copy you already have: ```bash perl -pi -e 's/\r$//' snap.sh # or: sed -i'' -e 's/\r$//' snap.sh git config core.autocrlf input # stop it coming back ``` This repo ships a `.gitattributes` pinning `*.sh` to `eol=lf`, so a fresh clone is safe. ### 1c. Cloud or bridged sessions: no route to the LAN **Symptom:** a `403` whose headers name a proxy, e.g. `X-Proxy-Error: blocked-by-allowlist` — or a plain connection failure with no HTTP response at all. If Claude runs in a cloud session with a device bridge (Cowork and similar), your camera is on a network that session cannot reach. This is **not** the Claude Code Bash sandbox, and no local settings change opens it — the allowlist belongs to the bridge, not to you. `snap.sh` prints whatever the proxy says about itself so you can tell which system refused you. **`snap.sh` now bypasses the proxy for LAN cameras automatically** — it passes `--noproxy <camera-host>` whenever the camera is on a private address, so a proxy that could never serve a LAN address is simply not consulted. Public hosts keep using the proxy, since for them it may be the only route out. That covers the common corporate-proxy case. Two traps remain worth knowing: - **`no_proxy` CIDR entries need curl 7.86+.** `no_proxy=192.168.0.0/16` looks right and is *silently ignored* by older builds — which is why the explicit `--noproxy` above is used instead of relying on it. - **Bypassing the proxy doesn't help if the container has no LAN route at all.** Nothing in a script can fix that; use the browser route below. **What works instead:** fetch the snapshot from a browser running on the LAN host (e.g. Claude in Chrome opening `http://<camera-ip>:8080/shot.jpg`), which bypasses the session's egress entirely. Confirmed in the field: full page text and small print were legible that way. It is also, in the words of the person who found it, "SUPER clunky" — so it is a workaround, not an answer. 📌 Tracked in **[issue #2](https://github.com/fcavalcantirj/claude-code-eyes/issues/2)**, with a one-command triage that tells this apart from the two fixable causes above. Running into it? Please add your setup to the **[cloud-session discussion](https://github.com/fcavalcantirj/claude-code-eyes/discussions/3)** — more datapoints make the upstream case stronger. ### 2. Frames written to `$TMPDIR` were unreadable **Symptom:** `snap.sh` prints a path, but `Read` cannot open it. Sandboxed commands get a *different* `$TMPDIR` than the Read tool sees, so a `$TMPDIR` path is not a shared address between them. `snap.sh` therefore writes frames under the working directory (`./.claude-code-eyes/`), which both agree on. Add that directory to your project's `.gitignore`. ### 3. Your phone was simply asleep **Symptom:** the first capture fails, a retry moments later succeeds. Android dozes the Wi-Fi radio, so the IP Webcam server refuses the first connection while the phone wakes. `snap.sh` retries 3 times before giving up. --- ## Why this exists I'm a quadriplegic developer. I'm fluent in code, and I knew **nothing** about electronics or IoT — I'd never wired a board in my life. So I ran an experiment: could Claude Code connect an ESP32 to my system and just… do the whole thing? It did. Given a goal, my Wi-Fi, and the API it would talk to, Claude designed the architecture, wrote the firmware and a relay service, flashed the board, ran OTA updates, and wrote its own tests. The part I didn't expect: it **fixed the UI on the little display**. A 48-pixel clock font was silently dropping characters — handed `~1h23min` it rendered **`1 24m`** on the panel — and every automated test stayed green, because the bytes really *were* ASCII; the narrow thing was the font's glyph coverage, which lives on the glass and nowhere else. Claude only caught it by *looking* at the panel. And that's where the friction was. Before this skill, "let Claude see the board" meant a soul-crushing manual loop: screenshot the display → send it to myself over WhatsApp → download it → paste it into Claude Code. Every. Single. Iteration. `claude-code-eyes` deletes that loop — Claude grabs the frame itself, reads it, fixes the code, reflashes, and looks again. > **"This is fucking awesome. And yeah — I'm a quad developer."** *Honest footnote: I still set the spec, plugged in the cable, and pressed the button — and on one layout bug it was my own eyes that caught what Claude had already marked "pass." Eyes help; they're not infallible. That humility is baked into the skill: it refuses a blurry frame, and it knows what an instrument can and cannot see — a blank frame is not a "no" until the camera is proven to be looking.* --- ## License MIT — see [LICENSE](LICENSE).tests/README.md1.7 KB6ab22308bedcupstream ↗
# Tests No camera required — a fixture HTTP server stands in for one, including the IP Webcam control surface (`/settings/zoom`, `/focus`, `/status.json`). ```bash bash tests/run_tests.sh # from anywhere in the repo bash tests/run_tests.sh /path/to/a/copy # or point it at another checkout ``` Prints one line per check and exits non-zero if any fail. The runner starts and stops its own fixtures; nothing is left listening. ## What's covered Backends, watch mode, config precedence, the `CCE_KEYS` allowlist boundary, the non-image guard, HTTP basic auth, output directory + `CCE_OUT_DIR`, retry, zoom and focus (including that zoom is **restored** afterwards), `setup.sh` behaviour, CRLF detection, and failure diagnosis — 401 vs 4xx vs proxy-403 vs no-response, and that a sandbox is never blamed when the evidence doesn't support it. ## Two things that will bite you **curl never routes loopback through a proxy.** The proxy-bypass test therefore binds a second fixture to `0.0.0.0` and uses the machine's real LAN address. A test written against `127.0.0.1` passes whether the code is right or wrong. It self-skips when no LAN address is available. **Plant the failure first.** Before trusting a new assertion, break the code on purpose and confirm *that* test — and only that test — goes red. Every check here was introduced that way; several passed for the wrong reason until the mutation exposed them. ## Adding a case Use `ok` / `no` / `chk` and `newdir` (which gives each case a clean working directory, since `snap.sh` writes frames to `$PWD`). Keep it bash 3.2-safe: it must run under macOS's `/bin/bash` 3.2, so no `declare -A`, no GNU-only flags, and use `grep -E` rather than escaped BRE alternation..gitattributes613 B28ceab151400upstream ↗
# Shell scripts MUST keep LF endings. git's core.autocrlf defaults to true on # Windows, and a CRLF-converted snap.sh dies before it runs a single command: # snap.sh: line 29: $'\r': command not found # snap.sh: line 30: set: pipefail: invalid option name # (Reported from the field 2026-08-20.) bash cannot self-diagnose this -- it is # already dead -- so the only real defence is to never let the conversion happen. *.sh text eol=lf *.md text eol=lf *.json text eol=lf .gitignore text eol=lf .gitattributes text eol=lf # Binary assets: never touch them. *.png binary *.gif binary *.jpg binary.gitignore333 B10f3516b5b90upstream ↗
# Secrets & local camera config — never commit these .env .env.* .cce.env *.token secrets* # Captured frames (snap.sh writes to ./.claude-code-eyes) .claude-code-eyes/ frame-*.jpg frame-*.jpeg frame-*.png frames/ # OS / editor cruft .DS_Store # Local launch / planning docs — not part of the public skill LAUNCH.md handovers/banner.svg4.9 KB0e8245bd738cupstream ↗
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 320" width="1280" height="320" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"> <defs> <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"> <stop offset="0%" stop-color="#0d1320"/> <stop offset="45%" stop-color="#0b0f18"/> <stop offset="100%" stop-color="#05070b"/> </linearGradient> <radialGradient id="iris" cx="50%" cy="50%" r="50%"> <stop offset="0%" stop-color="#22d3ee" stop-opacity="0.38"/> <stop offset="55%" stop-color="#0b4a63" stop-opacity="0.35"/> <stop offset="100%" stop-color="#05070a" stop-opacity="0"/> </radialGradient> <radialGradient id="halo" cx="50%" cy="50%" r="50%"> <stop offset="0%" stop-color="#22d3ee" stop-opacity="0.12"/> <stop offset="100%" stop-color="#22d3ee" stop-opacity="0"/> </radialGradient> <filter id="glow" x="-60%" y="-60%" width="220%" height="220%"> <feGaussianBlur stdDeviation="4" result="b"/> <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge> </filter> <pattern id="grid" width="34" height="34" patternUnits="userSpaceOnUse"> <circle cx="1" cy="1" r="1" fill="#8fb7d6" opacity="0.05"/> </pattern> </defs> <!-- frame --> <rect x="2" y="2" width="1276" height="316" rx="16" fill="url(#bg)" stroke="#1b2431" stroke-width="2"/> <rect x="2" y="2" width="1276" height="316" rx="16" fill="url(#grid)"/> <!-- viewfinder corner brackets --> <g stroke="#38bdf8" stroke-width="2.5" opacity="0.55" fill="none" stroke-linecap="round"> <path d="M28 30 h56 M30 28 v56"/> <path d="M1252 30 h-56 M1250 28 v56"/> <path d="M28 290 h56 M30 292 v-56"/> <path d="M1252 290 h-56 M1250 292 v-56"/> </g> <!-- REC indicator --> <g> <circle cx="1150" cy="42" r="6" fill="#ff5f56" filter="url(#glow)"/> <text x="1166" y="47" fill="#ff8b84" font-size="15" font-weight="700" letter-spacing="2">REC</text> </g> <!-- ==== EYE / APERTURE ==== --> <g> <circle cx="200" cy="160" r="150" fill="url(#halo)"/> <!-- eyelid almond --> <path d="M70 160 C130 92 270 92 330 160 C270 228 130 228 70 160 Z" fill="#0a1120" stroke="#38bdf8" stroke-width="3" filter="url(#glow)"/> <!-- iris glow + rings --> <circle cx="200" cy="160" r="66" fill="url(#iris)"/> <circle cx="200" cy="160" r="72" fill="none" stroke="#38bdf8" stroke-width="1" opacity="0.35" stroke-dasharray="2 6"/> <circle cx="200" cy="160" r="66" fill="none" stroke="#7dd3fc" stroke-width="2.2"/> <!-- aperture blades (spokes) --> <g stroke="#38bdf8" stroke-width="1.6" opacity="0.65" stroke-linecap="round"> <line x1="228.6" y1="176.5" x2="254.6" y2="191.5"/> <line x1="200" y1="193" x2="200" y2="223"/> <line x1="171.4" y1="176.5" x2="145.4" y2="191.5"/> <line x1="171.4" y1="143.5" x2="145.4" y2="128.5"/> <line x1="200" y1="127" x2="200" y2="97"/> <line x1="228.6" y1="143.5" x2="254.6" y2="128.5"/> </g> <!-- aperture opening --> <polygon points="238,160 219,192.9 181,192.9 162,160 181,127.1 219,127.1" fill="#05080d" stroke="#7dd3fc" stroke-width="1.5"/> <circle cx="200" cy="160" r="13" fill="#04070c"/> <circle cx="192" cy="152" r="4" fill="#d6f4ff" opacity="0.9"/> <!-- focus box --> <g stroke="#f5a623" stroke-width="2.4" opacity="0.85" fill="none" stroke-linecap="round"> <path d="M96 66 h30 M96 66 v30"/> <path d="M304 66 h-30 M304 66 v30"/> <path d="M96 254 h30 M96 254 v-30"/> <path d="M304 254 h-30 M304 254 v-30"/> <path d="M200 66 v12 M200 254 v-12 M96 160 h12 M304 160 h-12" opacity="0.7"/> </g> </g> <!-- ==== WORDMARK ==== --> <text x="378" y="150" font-size="60" font-weight="700" letter-spacing="-1"> <tspan fill="#e6edf3">claude-code-</tspan><tspan fill="#38bdf8" filter="url(#glow)">eyes</tspan> </text> <rect x="382" y="168" width="150" height="3" rx="1.5" fill="#38bdf8" opacity="0.8"/> <rect x="536" y="168" width="70" height="3" rx="1.5" fill="#f5a623" opacity="0.8"/> <text x="382" y="204" font-size="23" fill="#9aa7b4">Give Claude Code eyes for the real world.</text> <text x="382" y="236" font-size="16" fill="#6e7c8a">Catch what no test can · verify wiring before power-on.</text> <text x="382" y="270" font-size="15" fill="#4d5a68" letter-spacing="0.5">IP Webcam · camera-streamer · any snapshot URL</text> <!-- easter egg: the bug only eyes caught --> <text x="1018" y="236" font-size="11" fill="#56606a">◂ the bug only eyes caught</text> <g> <rect x="1018" y="244" width="214" height="52" rx="6" fill="#04120a" stroke="#16432680" stroke-width="1.5"/> <text x="1034" y="280" font-size="26" fill="#3fb950" letter-spacing="1">~1h23min</text> </g> <!-- HUD footer --> <text x="40" y="298" font-size="13" fill="#5a6672" letter-spacing="1">CAM_01 · /shot.jpg · image/jpeg · snapshot</text> </svg>CLAUDE.md4.3 KB24da1cf61326upstream ↗
# claude-code-eyes — notes for Claude Code This repository **is** a single Claude Code skill (repo root = the skill folder). If you're editing it with Claude Code, keep the invariants below — each was learned the hard way, and the tests/validator won't always catch you breaking them. ## What it is A camera-vision skill. `snap.sh` grabs a frame from a snapshot-capable camera and prints its path; Claude `Read`s the path to *see* it. `SKILL.md` is the skill itself; `setup.sh` writes the camera config and verifies it; the rest is docs/metadata. ## Load-bearing invariants (do not "simplify" these away) - **The `CCE_KEYS` allowlist in `snap.sh` and `setup.sh` is a security boundary.** Config files (`./.cce.env`, `~/.config/claude-code-eyes/config`) are *parsed*, never `source`d — a config file must not be able to execute code or set arbitrary variables. The allowlist check runs **before** the value ever reaches `eval`/`printf -v`. Keep it exactly there. - **Never ship a backend you haven't actually run.** The local `ffmpeg` webcam path is documented in the README but deliberately **not** implemented in `snap.sh`, because it can't be tested headlessly (macOS gates camera access behind an interactive permission prompt). Mark untested things untested, or leave them out. - **Keep the soul.** The reason this beats a one-line `curl | Read` is the three disciplines in `SKILL.md`: visual-verify (catch what green tests can't), the wiring-mentor protocol, and "know what your instrument can and cannot see." Don't trim `SKILL.md` back down to a webcam grab. - **`snap.sh` must stay portable to bash 3.2** (the default `/bin/bash` on macOS) and Linux. Preserve the empty-array-under-`set -u` guard (`${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"}`), avoid GNU-only flags, and write output to `${TMPDIR:-/tmp}`. ## Frontmatter rules (enforced by the skill-creator validator) `SKILL.md` frontmatter allows only these keys: `name, description, license, allowed-tools, metadata, compatibility`. `name` is kebab-case, ≤ 64 chars. **`description` is ≤ 1024 chars and must contain NO angle brackets** (`<` `>`) — write usage hints as words, not with bracketed placeholders. Validate with the skill-creator plugin's `quick_validate.py <skill-dir>` (prints `Skill is valid!`, exit 0). ## How to test (everything must pass under bash 3.2) **There is a real suite now — use it before hand-rolling anything:** ```bash bash tests/run_tests.sh # 51 checks, starts/stops its own fixtures ``` See `tests/README.md`. The manual recipe below is still the way to check something the suite doesn't cover yet; add a case for whatever you find. No real camera is needed — serve a JPEG over HTTP and point the script at it: ```bash bash -n snap.sh setup.sh # syntax first # a tiny JPEG fixture + a throwaway server python3 -c 'import base64;open("shot.jpg","wb").write(base64.b64decode(b"/9j/4AAQSkZJRgABAQEAYABgAAD/2Q=="))' 2>/dev/null || : # use any real jpg python3 -m http.server 8099 --bind 127.0.0.1 & CCE_CAM_TYPE=url CCE_CAM_URL=http://127.0.0.1:8099/shot.jpg bash snap.sh # -> prints a path; `file --mime-type <path>` must report image/jpeg ``` Cover, at minimum: the no-config error path (exit 1), all three backends (`ipwebcam`/`camera-streamer`/`url`), watch mode (`snap.sh 3 1` → 3 frames), env-beats-`.cce.env` precedence, the non-image magic-byte guard (an HTML `200` body must be rejected), an unknown `CCE_CAM_TYPE` (exit 2), and HTTP basic auth. For `setup.sh`: `--url` writes + verifies, a dead camera still saves the config with a friendly message (exit 0), and `--scan` discovers a fixture on the LAN. **Plant the failure first:** before trusting a test, make it go red on demand. ## Adding a camera backend 1. Add the type to the `case` in `snap.sh` (endpoint mapping) **and** to `setup.sh`'s `endpoint_for` plus the valid-type lists in both. 2. If it isn't an HTTP snapshot (e.g. a local capture), only ship it if you can test it non-interactively; otherwise document it in the README as experimental, like the `ffmpeg` path. 3. Add a test that proves it, and a row in the README + `SKILL.md` backend tables. ## Conventions Single-skill repo: root = skill folder, so `git clone` straight into `~/.claude/skills/…` works. No secrets in git (`.gitignore` covers `.env`/`.cce.env`/tokens/captured frames). MIT licensed.demo.gif7.1 MB66c2b6a79730upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
evals/evals.json1.3 KB7a70fcd406b7upstream ↗
[ { "query": "Are you seeing this? Is the yellow jumper in the right pin?", "should_trigger": true }, { "query": "olha isso, acho que inverti a polaridade do JST", "should_trigger": true }, { "query": "Look at the display and tell me if it shows the full countdown or if any characters are cut off", "should_trigger": true }, { "query": "Watch this — I'm about to press the button, tell me what changes on the panel", "should_trigger": true }, { "query": "Can you check the camera and confirm the LED strip actually lit up?", "should_trigger": true }, { "query": "Before I power it on, does this wiring match the table? Any 5V on a 3.3V pin?", "should_trigger": true }, { "query": "What's this part on the breadboard? Zoom in if you can read the label.", "should_trigger": true }, { "query": "The screen looks blank — is it stale or is the render actually broken?", "should_trigger": true }, { "query": "Refactor this function to use async/await instead of callbacks", "should_trigger": false }, { "query": "Why is my unit test failing with a null pointer exception?", "should_trigger": false }, { "query": "Summarize the changes in the last three git commits", "should_trigger": false }, { "query": "What's the difference between a mutex and a semaphore?", "should_trigger": false } ]LICENSE1.0 KB319c4d2bd705upstream ↗
MIT License Copyright (c) 2026 Felipe Cavalcanti Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.setup.sh9.6 KB3d1c67cb955bupstream ↗
#!/bin/bash # claude-code-eyes setup -- one command from install to working. # # Usage: # setup.sh interactive: asks for the camera URL (blank = scan the LAN) # setup.sh --url URL non-interactive; --type/--auth/--local optional # setup.sh --scan just scan the LAN for an IP Webcam and print matches # setup.sh --show show where the config is / would be written # # Options: # --type ipwebcam|camera-streamer|url (default: ipwebcam) # --url URL camera URL (interpreted per --type) # --auth user:pass optional HTTP basic auth # --local write ./.cce.env instead of the global config # # Writes the same config snap.sh reads; contains no secrets beyond what you provide. set -euo pipefail # Absolute path to the snap.sh sitting beside this script -- excludedCommands is # matched exact/prefix, so the advice must name the real invocation, not "snap.sh". SELF_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)" SNAP_PATH="${SELF_DIR:-.}/snap.sh" TYPE=""; URL=""; AUTH=""; TARGET="global"; ACTION="setup" while [ $# -gt 0 ]; do case "$1" in --type) TYPE="${2:-}"; shift 2 ;; --url) URL="${2:-}"; shift 2 ;; --auth) AUTH="${2:-}"; shift 2 ;; --local) TARGET="local"; shift ;; --global) TARGET="global"; shift ;; --scan) ACTION="scan"; shift ;; --show) ACTION="show"; shift ;; -h|--help) sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; *) echo "unknown argument: $1 (try --help)" >&2; exit 2 ;; esac done XDG="${XDG_CONFIG_HOME:-$HOME/.config}" GLOBAL_CFG="$XDG/claude-code-eyes/config" LOCAL_CFG="./.cce.env" # --- CRLF guard -------------------------------------------------------------- # A Windows-saved or autocrlf-converted snap.sh dies before running anything: # snap.sh: line N: $'\r': command not found # snap.sh: line N: set: pipefail: invalid option name # snap.sh cannot report this itself (bash is already dead), so check it here. crlf_check() { local snap="${SELF_DIR:-.}/snap.sh" crs [ -f "$snap" ] || return 0 crs="$(tr -cd '\r' < "$snap" | wc -c | tr -d ' ')" [ "$crs" = "0" ] && return 0 echo "WARNING: $snap has CRLF (Windows) line endings -- $crs carriage returns." >&2 echo " bash will fail on it with \"set: pipefail: invalid option name\" before it" >&2 echo " ever reaches your camera. Fix it with either of:" >&2 echo " perl -pi -e 's/\\r\$//' \"$snap\"" >&2 echo " sed -i'' -e 's/\\r\$//' \"$snap\"" >&2 echo " Then re-clone with .gitattributes present, or set: git config core.autocrlf input" >&2 return 1 } # --- probe one URL: 0 if it returns a JPEG/PNG ------------------------------- is_image_url() { # $1=url $2=auth(optional) $3=connect-timeout local u="$1" a="${2:-}" ct="${3:-2}" tmp sig args tmp="$(mktemp)" args=(-sf --connect-timeout "$ct" --max-time 8) [ -n "$a" ] && args=("${args[@]}" -u "$a") if curl "${args[@]}" "$u" -o "$tmp" 2>/dev/null; then sig="$(od -An -tx1 -N4 "$tmp" 2>/dev/null | tr -d ' \n')" rm -f "$tmp" case "$sig" in ffd8ff*|89504e47) return 0 ;; esac fi rm -f "$tmp"; return 1 } # --- endpoint for a (type,url) pair, mirroring snap.sh ----------------------- endpoint_for() { # $1=type $2=url local base="${2%/}" case "$1" in ipwebcam) printf '%s\n' "$base/shot.jpg" ;; camera-streamer) printf '%s\n' "$base/snapshot" ;; *) printf '%s\n' "$2" ;; esac } # --- host:port of a URL, mirroring snap.sh ----------------------------------- host_port() { # "http://u:[email protected]:8080/shot.jpg" -> "1.2.3.4:8080" local u="${1#*://}" u="${u##*@}" printf '%s\n' "${u%%/*}" } # --- Claude Code Bash sandbox --------------------------------------------------- # Verified against Claude Code 2.1.236: the sandbox blocks private/LAN addresses # below its proxy, and sandbox.network.allowedDomains cannot admit them ("Public # domain names are required"). A LAN camera therefore needs the capture command # excluded from the sandbox; only a public host is fixed by the allowlist. is_private_host() { # $1=host[:port] local h="${1%%:*}" case "$h" in localhost|*.local|*.internal|*.localdomain) return 0 ;; 10.*|127.*|169.254.*|192.168.*) return 0 ;; 172.1[6-9].*|172.2[0-9].*|172.3[01].*) return 0 ;; esac return 1 } sandbox_hint() { # $1=endpoint local hp; hp="$(host_port "$1")" echo echo "Claude Code runs Bash in a sandbox. If Claude cannot reach the camera but your" echo "own terminal can, that is why. Add to ~/.claude/settings.json, then restart:" echo if is_private_host "$hp"; then echo " { \"sandbox\": { \"excludedCommands\": [\"bash $SNAP_PATH\"] } }" echo echo "$hp is a private/LAN address; the network allowlist cannot admit those" echo "(it requires public domain names), so the capture must run outside the sandbox." echo "The path must match how it is invoked -- matching is exact/prefix, not fuzzy." echo "You can also just approve Claude's offer to retry the command outside the" echo "sandbox; that works with no config change." else echo " { \"sandbox\": { \"network\": { \"allowedDomains\": [\"$hp\"] } } }" echo echo "IPs must be listed EXACTLY -- wildcards never match an IP." fi echo "Inspect the active policy with /sandbox. https://code.claude.com/docs/en/sandboxing" } # --- local /24 prefix (best effort) ------------------------------------------ lan_prefix() { # echoes e.g. 192.168.0 local ip="" case "$(uname -s)" in Darwin) ip="$(ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null || true)" ;; *) ip="$(hostname -I 2>/dev/null | awk '{print $1}')" ;; esac [ -n "$ip" ] || return 1 printf '%s\n' "${ip%.*}" } # --- scan the /24 on :8080 for an IP Webcam /shot.jpg ------------------------ scan_lan() { # prints found base URLs, one per line local prefix n prefix="$(lan_prefix)" || { echo "could not determine your LAN subnet" >&2; return 1; } echo "scanning ${prefix}.1-254 on port 8080 for an IP Webcam ..." >&2 local out; out="$(mktemp)" n=1 while [ "$n" -le 254 ]; do ( is_image_url "http://${prefix}.${n}:8080/shot.jpg" "" 1 && printf '%s\n' "http://${prefix}.${n}:8080" >> "$out" ) & [ $(( n % 48 )) -eq 0 ] && wait n=$(( n + 1 )) done wait sort -u "$out"; rm -f "$out" } write_config() { # $1=type $2=url $3=auth $4=target local t="$1" u="$2" a="$3" tgt="$4" file if [ "$tgt" = "local" ]; then file="$LOCAL_CFG"; else file="$GLOBAL_CFG"; mkdir -p "$(dirname "$file")"; fi { echo "CCE_CAM_TYPE=$t" echo "CCE_CAM_URL=$u" [ -n "$a" ] && echo "CCE_CAM_AUTH=$a" } > "$file" chmod 600 "$file" printf '%s\n' "$file" } # --- actions ----------------------------------------------------------------- crlf_check || true # warn loudly, but never block the user if [ "$ACTION" = "show" ]; then echo "global config: $GLOBAL_CFG $( [ -f "$GLOBAL_CFG" ] && echo '(exists)' || echo '(not set)')" echo "local config: $LOCAL_CFG $( [ -f "$LOCAL_CFG" ] && echo '(exists)' || echo '(not set)')" exit 0 fi if [ "$ACTION" = "scan" ]; then matches="$(scan_lan || true)" if [ -n "$matches" ]; then echo "found IP Webcam(s):"; printf '%s\n' "$matches" else echo "no IP Webcam found on the LAN (is the app's server running?)." fi exit 0 fi # setup (interactive if --url not given) if [ -z "$URL" ]; then printf 'Camera URL (e.g. http://192.168.0.42:8080), or blank to scan the LAN: ' >&2 IFS= read -r URL || true if [ -z "$URL" ]; then matches="$(scan_lan || true)" if [ -n "$matches" ]; then echo "found:" >&2; printf '%s\n' "$matches" | nl -w2 -s') ' >&2 printf 'pick a number (or paste a URL): ' >&2; IFS= read -r pick || true case "$pick" in ''|*[!0-9]*) URL="$pick" ;; *) URL="$(printf '%s\n' "$matches" | sed -n "${pick}p")" ;; esac fi [ -n "$URL" ] || { echo "no camera URL provided; nothing written." >&2; exit 1; } fi if [ -z "$TYPE" ]; then printf 'Type [ipwebcam]/camera-streamer/url: ' >&2; IFS= read -r TYPE || true fi if [ -z "$AUTH" ]; then printf 'Basic auth user:pass (blank for none): ' >&2; IFS= read -r AUTH || true fi fi TYPE="${TYPE:-ipwebcam}" case "$TYPE" in ipwebcam|camera-streamer|url) ;; *) echo "invalid --type '$TYPE'" >&2; exit 2 ;; esac file="$(write_config "$TYPE" "$URL" "$AUTH" "$TARGET")" echo "wrote $file (mode 600): CCE_CAM_TYPE=$TYPE, CCE_CAM_URL=$URL, auth=$([ -n "$AUTH" ] && echo set || echo none)" ep="$(endpoint_for "$TYPE" "$URL")" printf 'verifying %s ... ' "$ep" if is_image_url "$ep" "$AUTH" 3; then echo "OK -- got a live frame. You're set: ask Claude \"are you seeing this?\"" # report zoom/focus support, so the user knows whether --zoom is available if [ "$TYPE" = "ipwebcam" ]; then steps="$(curl -sf -m 6 ${AUTH:+-u "$AUTH"} "${URL%/}/status.json?show_avail=1" 2>/dev/null \ | grep -o '"zoom":\[[^]]*\]' | grep -o '[0-9][0-9]*' | wc -l | tr -d ' ')" if [ -n "$steps" ] && [ "$steps" -gt 1 ]; then echo " zoom + focus available ($steps zoom steps): try snap.sh --zoom 4 / snap.sh --focus" else echo " this camera reports no zoom steps; --zoom will capture at current settings" fi fi else echo "no frame right now." echo " The config is saved and correct; the camera just isn't reachable this moment" echo " (start the phone's IP Webcam server / check the IP). It'll work once it's up." fi sandbox_hint "$ep"snap.sh18 KB79b38c81688cupstream ↗
#!/bin/bash # claude-code-eyes: grab current frame(s) from a snapshot-capable camera and # print the JPEG/PNG path(s), one per line, for Claude to Read. # # Usage: snap.sh [--zoom N] [--focus] [count] [interval_seconds] # snap.sh -> 1 frame now # snap.sh 3 2 -> 3 frames, 2s apart (watch mode) # snap.sh --zoom 4 -> zoom 4x, capture, then restore the previous zoom # snap.sh --focus -> trigger autofocus, then capture # # --zoom / --focus need CCE_CAM_TYPE=ipwebcam (Android "IP Webcam"). Other # backends say so and still capture. N is a magnification from 1 to 10. # # Config (highest precedence first): # 1. Environment variables already exported in the shell # 2. ./.cce.env (current working directory) # 3. $XDG_CONFIG_HOME/claude-code-eyes/config (default ~/.config/...) # Config files only FILL empty variables; exported env always wins. # # Keys: # CCE_CAM_URL camera URL (meaning depends on CCE_CAM_TYPE) # CCE_CAM_AUTH optional HTTP basic auth "user:pass" # CCE_CAM_TYPE ipwebcam | camera-streamer | url (default: url) # CCE_OUT_DIR where frames are written (default: ./.claude-code-eyes) # # Frames go under the WORKING DIRECTORY, not $TMPDIR, on purpose: Claude Code's # Bash sandbox gives sandboxed commands a different $TMPDIR than the (unsandboxed) # Read tool sees, so a $TMPDIR path printed here can be unreadable there. The # working directory is the one location both agree on. # See https://code.claude.com/docs/en/sandboxing # # Backends: # ipwebcam GET $CCE_CAM_URL/shot.jpg (Android "IP Webcam" app) # camera-streamer GET $CCE_CAM_URL/snapshot (Raspberry Pi camera-streamer) # url GET $CCE_CAM_URL (verbatim; full snapshot URL) # # Portable: macOS bash 3.2 and Linux. Runs from any directory. set -euo pipefail # Absolute path to this script. The sandbox advice below has to name the command # the way it is ACTUALLY invoked: Claude Code matches excludedCommands with # prefix: cmd === entry || cmd.startsWith(entry + " ") exact: cmd === entry # so a bare "bash snap.sh" never matches "bash /path/to/snap.sh". Using the # absolute path as a prefix also covers watch mode ("... snap.sh 3 2"). SELF_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)" if [ -n "$SELF_DIR" ]; then SELF="$SELF_DIR/$(basename "$0")"; else SELF="$0"; fi # The security boundary: config files may set ONLY these keys. This allowlist is # load-bearing -- it is checked below BEFORE the value ever reaches eval/printf, # so a .cce.env cannot inject arbitrary variables (and cannot execute code, since # the loader never `source`s the file). Do not move or remove this check. CCE_KEYS="CCE_CAM_URL CCE_CAM_AUTH CCE_CAM_TYPE CCE_OUT_DIR" # precedence-respecting config loader (bash 3.2 safe; no `source`, no code exec) load_config_file() { local file="$1" line key val cur [ -f "$file" ] || return 0 while IFS= read -r line || [ -n "$line" ]; do line="${line#"${line%%[![:space:]]*}"}" # ltrim case "$line" in ''|\#*) continue ;; esac # blank / comment case "$line" in export[[:space:]]*) line="${line#export}" # tolerate `export K=V` line="${line#"${line%%[![:space:]]*}"}" ;; esac case "$line" in *=*) ;; *) continue ;; esac # need a KEY=VALUE key="${line%%=*}"; val="${line#*=}" key="${key#"${key%%[![:space:]]*}"}"; key="${key%"${key##*[![:space:]]}"}" # allowlist gate -- only recognized keys pass; everything else is ignored case " $CCE_KEYS " in *" $key "*) ;; *) continue ;; esac case "$val" in # strip one quote pair \"*\") val="${val#\"}"; val="${val%\"}" ;; \'*\') val="${val#\'}"; val="${val%\'}" ;; esac eval "cur=\${$key:-}" # key is allowlisted [ -n "$cur" ] && continue # exported env wins printf -v "$key" '%s' "$val" # fill the gap done < "$file" } load_config_file "./.cce.env" XDG="${XDG_CONFIG_HOME:-$HOME/.config}" load_config_file "$XDG/claude-code-eyes/config" CCE_CAM_TYPE="${CCE_CAM_TYPE:-url}" case "$CCE_CAM_TYPE" in ipwebcam|camera-streamer|url) ;; *) echo "ERROR: unknown CCE_CAM_TYPE='$CCE_CAM_TYPE' (valid: ipwebcam, camera-streamer, url)" >&2 exit 2 ;; esac if [ -z "${CCE_CAM_URL:-}" ]; then echo "ERROR: no CCE_CAM_URL configured for CCE_CAM_TYPE=$CCE_CAM_TYPE." >&2 echo " Set env CCE_CAM_URL, or add it to ./.cce.env or $XDG/claude-code-eyes/config" >&2 echo " (checked: shell env, ./.cce.env, $XDG/claude-code-eyes/config)" >&2 exit 1 fi base="${CCE_CAM_URL%/}" # strip one trailing / case "$CCE_CAM_TYPE" in ipwebcam) ENDPOINT="$base/shot.jpg" ;; camera-streamer) ENDPOINT="$base/snapshot" ;; url) ENDPOINT="$CCE_CAM_URL" ;; # verbatim contract esac ZOOM=""; DO_FOCUS=0; POS=() while [ $# -gt 0 ]; do case "$1" in --zoom) ZOOM="${2:-}"; shift 2 ;; --focus) DO_FOCUS=1; shift ;; --) shift; break ;; -*) echo "ERROR: unknown option '$1' (valid: --zoom N, --focus)" >&2; exit 2 ;; *) POS[${#POS[@]}]="$1"; shift ;; esac done set -- ${POS[@]+"${POS[@]}"} # --zoom takes a magnification (1..10), not raw device units. The device scale is # 100..1000 where 100 = 1x, so units = N*100, then snapped to an allowed step. ZOOM_UNITS="" if [ -n "$ZOOM" ]; then case "$ZOOM" in ''|*[!0-9.]*|*.*.*) echo "ERROR: --zoom takes a number from 1 to 10 (got '$ZOOM')" >&2; exit 2 ;; esac ZOOM_UNITS="$(awk -v z="$ZOOM" 'BEGIN{printf "%d", z*100}')" if [ "$ZOOM_UNITS" -lt 100 ] || [ "$ZOOM_UNITS" -gt 1000 ]; then echo "ERROR: --zoom must be between 1 and 10 (got '$ZOOM')" >&2; exit 2 fi fi COUNT="${1:-1}"; INTERVAL="${2:-2}" case "$COUNT" in ''|*[!0-9]*) echo "ERROR: count must be a positive integer" >&2; exit 2 ;; esac case "$INTERVAL" in ''|*[!0-9]*) echo "ERROR: interval must be an integer (seconds)" >&2; exit 2 ;; esac [ "$COUNT" -ge 1 ] || { echo "ERROR: count must be >= 1" >&2; exit 2; } OUT_DIR="${CCE_OUT_DIR:-$PWD/.claude-code-eyes}"; mkdir -p "$OUT_DIR" # empty-array-under-set-u guard (bash 3.2 safe) -- see AUTH_ARGS expansion below AUTH_ARGS=() [ -n "${CCE_CAM_AUTH:-}" ] && AUTH_ARGS=(-u "$CCE_CAM_AUTH") NOPROXY_ARGS=() # populated below, once the host is classified # --- camera control ---------------------------------------------------------- # Verified against IP Webcam on a real phone, 2026-08-20: # /settings/zoom?set=V absolute; V must be one of avail.zoom (100=1x .. 1000=max) # /ptz?zoom=P PERCENT 0..100, NOT absolute -- ptz?zoom=200 slams to max # /focus /nofocus momentary trigger; focusmode is unchanged # success = the response BODY contains "Ok" (the status code is 200 either way) # curvals.zoom LAGS the set by several seconds, so we poll instead of assuming # Note: pydroid-ipcam documents /settings/ptz?zoom=N -- that 404s on the device. ctrl_get() { # $1=path -> body on stdout, non-zero if unreachable curl -sf --connect-timeout 4 --max-time 10 \ ${NOPROXY_ARGS[@]+"${NOPROXY_ARGS[@]}"} \ ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} "$base$1" 2>/dev/null } ctrl_ok() { ctrl_get "$1" | grep -q "Ok"; } zoom_now() { ctrl_get "/status.json" | grep -o '"zoom":"[0-9]*"' | head -1 | grep -o '[0-9][0-9]*'; } zoom_avail() { ctrl_get "/status.json?show_avail=1" | grep -o '"zoom":\[[^]]*\]' | grep -o '[0-9][0-9]*'; } nearest_zoom() { # $1=target units -> closest allowed step local t="$1" best="" bd=999999 v d for v in $(zoom_avail); do if [ "$t" -gt "$v" ]; then d=$((t - v)); else d=$((v - t)); fi if [ "$d" -lt "$bd" ]; then bd="$d"; best="$v"; fi done printf '%s\n' "$best" } set_zoom() { # $1=units; waits out the status lag local v="$1" i=0 ctrl_ok "/settings/zoom?set=$v" || return 1 while [ "$i" -lt 8 ]; do [ "$(zoom_now)" = "$v" ] && return 0 sleep 1; i=$((i + 1)) done return 0 # applied; status just never caught up } ZOOM_ORIG="" restore_zoom() { # never leave the camera zoomed for the next capture [ -n "$ZOOM_ORIG" ] || return 0 ctrl_get "/settings/zoom?set=$ZOOM_ORIG" >/dev/null 2>&1 || true ZOOM_ORIG="" } trap restore_zoom EXIT INT TERM img_ext() { # echoes jpg|png, or "" if not an image local f="$1" sig [ -s "$f" ] || { echo ""; return 0; } sig="$(od -An -tx1 -N4 "$f" 2>/dev/null | tr -d ' \n')" case "$sig" in ffd8ff*) echo jpg ;; 89504e47) echo png ;; *) echo "" ;; esac } RETRIES=3 # phones (Android IP Webcam) refuse the first # connection while dozing; retry before giving up host_port() { # "http://u:[email protected]:8080/shot.jpg" -> "1.2.3.4:8080" local u="${1#*://}" u="${u##*@}" printf '%s\n' "${u%%/*}" } proxy_set() { # a proxy is configured (the sandbox always sets one) [ -n "${HTTP_PROXY:-}${HTTPS_PROXY:-}${ALL_PROXY:-}" ] && return 0 [ -n "${http_proxy:-}${https_proxy:-}${all_proxy:-}" ] && return 0 return 1 } # Why the HTTP status and not just "a proxy is set": inside Claude Code's sandbox a # proxy is ALWAYS set, so its presence says nothing about why a request failed. # Measured under a sandboxed session (Claude Code 2.1.236): # * a PUBLIC destination that is not allow-listed is refused by the proxy -> HTTP 403 # * a PRIVATE/LAN destination is blocked below the proxy -> connection failure, no status # * an allow-listed camera that is merely asleep ALSO gives a connection failure # So a connection failure is ambiguous and must never be reported as a sandbox verdict. # The two blocks also need DIFFERENT fixes: sandbox.network.allowedDomains rejects # private ranges outright ("Public domain names are required"), so a LAN camera can # only be reached by excluding the capture command from the sandbox. is_private_host() { # $1=host[:port] -> 0 if RFC1918 / loopback / .local local h="${1%%:*}" case "$h" in localhost|*.local|*.internal|*.localdomain) return 0 ;; 10.*|127.*|169.254.*|192.168.*) return 0 ;; 172.1[6-9].*|172.2[0-9].*|172.3[01].*) return 0 ;; esac return 1 } sandbox_fix() { # $1=host:port -- print the remedy that actually works local hp="$1" if is_private_host "$hp"; then echo " $hp is a private/LAN address. The sandbox blocks those below the proxy, and" >&2 echo " sandbox.network.allowedDomains cannot admit them (it requires public domains)." >&2 echo " Quickest: if Claude offers to retry the command outside the sandbox, approve it" >&2 echo " -- that captures the frame with no config change at all." >&2 echo " Permanent fix, in ~/.claude/settings.json:" >&2 echo " { \"sandbox\": { \"excludedCommands\": [\"bash $SELF\"] } }" >&2 echo " The path must match how it is invoked (matching is exact/prefix, not fuzzy);" >&2 echo " as a prefix this entry also covers watch mode." >&2 else echo " Fix: allow-list the camera in ~/.claude/settings.json, then restart Claude Code:" >&2 echo " { \"sandbox\": { \"network\": { \"allowedDomains\": [\"$hp\"] } } }" >&2 echo " IPs must be listed EXACTLY -- wildcards never match an IP." >&2 fi echo " Inspect the active policy with /sandbox. https://code.claude.com/docs/en/sandboxing" >&2 } proxy_verdict() { # $1=header file -- echo the proxy's own reason, if any [ -f "${1:-}" ] || return 1 grep -i -E '^(x-proxy-error|x-squid-error|proxy-agent|via|x-blocked-by):' "$1" 2>/dev/null \ | tr -d '\r' | head -3 } diagnose() { # $1=curl exit $2=http status ("000") $3=header file local rc="$1" code="$2" hdr="${3:-}" HP verdict HP="$(host_port "$ENDPOINT")" if [ "$code" = "403" ]; then echo "ERROR: $HP answered 403 Forbidden." >&2 verdict="$(proxy_verdict "$hdr" || true)" if [ -n "$verdict" ]; then echo " The refusal came from a proxy, which identified itself:" >&2 printf ' %s\n' "$verdict" >&2 fi if [ -n "$verdict" ] || proxy_set; then # Several different systems produce an identical 403 here. Name them rather # than assert one: a field report (2026-08-20) traced this exact shape to a # cloud device-bridge egress proxy, NOT to Claude Code's sandbox. echo " A 403 in front of a camera usually means one of:" >&2 echo " 1. a cloud or bridged session's egress proxy (its allowlist is the host's," >&2 echo " not yours -- a local settings change cannot open it), or" >&2 echo " 2. a corporate/system proxy, or" >&2 echo " 3. Claude Code's own Bash sandbox, if you run Claude Code locally, or" >&2 echo " 4. the camera itself rejecting the request." >&2 echo " If (3) applies:" >&2 sandbox_fix "$HP" echo " If your session has no route to the LAN at all, no setting fixes it --" >&2 echo " fetch the snapshot from a browser running on the LAN host instead." >&2 else echo " No proxy is configured for this shell, so this 403 came from the camera:" >&2 echo " it is reachable but refused this request (type=$CCE_CAM_TYPE, url=$ENDPOINT)." >&2 echo " Check the path for this backend, and whether the camera wants auth" >&2 echo " (CCE_CAM_AUTH is $([ -n "${CCE_CAM_AUTH:-}" ] && echo set || echo unset))." >&2 fi elif [ "$code" = "401" ]; then echo "ERROR: $HP returned 401 Unauthorized." >&2 echo " The camera wants HTTP basic auth. Set CCE_CAM_AUTH=user:pass" >&2 echo " (currently $([ -n "${CCE_CAM_AUTH:-}" ] && echo set || echo unset))." >&2 elif [ "$code" != "000" ] && [ "$code" != "200" ]; then echo "ERROR: $HP returned HTTP $code (type=$CCE_CAM_TYPE, url=$ENDPOINT)." >&2 echo " The host answered, so it is reachable -- check the path for this backend." >&2 else echo "ERROR: camera not reachable (type=$CCE_CAM_TYPE, url=$ENDPOINT, auth=$([ -n "${CCE_CAM_AUTH:-}" ] && echo set || echo none))." >&2 echo " Tried $RETRIES times, curl exit $rc -- no HTTP response at all." >&2 echo " Likely: camera app/server not running, phone asleep, IP or port changed," >&2 echo " or not on the same network." >&2 if proxy_set; then echo " This shell is sandboxed, which looks identical at this layer. If your own" >&2 echo " terminal CAN reach $HP but Claude cannot, it is the sandbox:" >&2 sandbox_fix "$HP" fi fi } # grab_one() runs inside a command substitution (a subshell), so it cannot export # state back to the caller -- it prints its own diagnosis to stderr (which is NOT # captured) and returns non-zero. Only the captured path goes to stdout. grab_one() { # $1=path prefix; prints final path on success local prefix="$1" tmp="$1.part" hdr="$1.hdr" ext attempt=1 code rc while :; do # no -f: let curl report the status instead of collapsing every 4xx into exit 22 if code="$(curl -s -o "$tmp" -D "$hdr" -w '%{http_code}' --connect-timeout 4 --max-time 15 \ ${NOPROXY_ARGS[@]+"${NOPROXY_ARGS[@]}"} \ ${AUTH_ARGS[@]+"${AUTH_ARGS[@]}"} "$ENDPOINT" 2>/dev/null)"; then rc=0 else rc=$?; code="000" fi [ "$rc" -eq 0 ] && [ "$code" = "200" ] && break # only a connection-level failure is worth retrying; an HTTP status is an answer if [ "$rc" -ne 0 ] && [ "$attempt" -lt "$RETRIES" ]; then attempt=$((attempt + 1)); sleep 1; continue fi rm -f "$tmp" diagnose "$rc" "$code" "$hdr" rm -f "$hdr" return 1 done ext="$(img_ext "$tmp")" if [ -z "$ext" ]; then rm -f "$tmp" echo "ERROR: endpoint returned non-image content (type=$CCE_CAM_TYPE, url=$ENDPOINT)." >&2 return 2 fi rm -f "$hdr" mv "$tmp" "$prefix.$ext" printf '%s\n' "$prefix.$ext" } # A camera on the LAN is never reachable *through* a proxy, so don't send it there. # Relying on no_proxy is not enough: CIDR entries like 192.168.0.0/16 need curl 7.86+ # and are silently ignored by older builds (seen in the field 2026-08-20). Passing # --noproxy for this host works on every version. Public hosts keep using the proxy, # since for them it may be the only route out. CAM_HOST="$(host_port "$ENDPOINT")" CAM_HOST="${CAM_HOST%%:*}" if is_private_host "$CAM_HOST"; then NOPROXY_ARGS=(--noproxy "$CAM_HOST") fi if [ -n "$ZOOM" ] || [ "$DO_FOCUS" -eq 1 ]; then if [ "$CCE_CAM_TYPE" != "ipwebcam" ]; then echo "NOTE: zoom/focus control needs CCE_CAM_TYPE=ipwebcam (this is $CCE_CAM_TYPE)." >&2 echo " Capturing at the camera's current settings instead." >&2 else if [ "$DO_FOCUS" -eq 1 ]; then if ctrl_ok "/focus"; then sleep 1; else echo "NOTE: this camera refused /focus; capturing anyway." >&2; fi fi if [ -n "$ZOOM" ]; then target="$(nearest_zoom "$ZOOM_UNITS")" if [ -z "$target" ]; then echo "NOTE: this camera reports no zoom control; capturing at current settings." >&2 else ZOOM_ORIG="$(zoom_now)"; [ -n "$ZOOM_ORIG" ] || ZOOM_ORIG=100 if set_zoom "$target"; then echo "zoom ${ZOOM}x -> $target (was $ZOOM_ORIG); will restore after capture" >&2 else echo "NOTE: this camera refused the zoom; capturing at current settings." >&2 ZOOM_ORIG="" fi fi fi fi fi i=1 while [ "$i" -le "$COUNT" ]; do prefix="$OUT_DIR/frame-$(date +%H%M%S)-$$-$i" if out="$(grab_one "$prefix")"; then printf '%s\n' "$out" else exit 1 # grab_one already explained the failure on stderr fi [ "$i" -lt "$COUNT" ] && sleep "$INTERVAL" i=$((i + 1)) done exit 0social-card.png171 KBff39c89506e6upstream ↗
Contents are not inlined in the catalog. Open the upstream file.
social-card.svg4.3 KBb24a966f3b16upstream ↗
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" width="1280" height="640" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"> <defs> <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"> <stop offset="0%" stop-color="#0d1320"/> <stop offset="45%" stop-color="#0b0f18"/> <stop offset="100%" stop-color="#05070b"/> </linearGradient> <radialGradient id="iris" cx="50%" cy="50%" r="50%"> <stop offset="0%" stop-color="#22d3ee" stop-opacity="0.38"/> <stop offset="55%" stop-color="#0b4a63" stop-opacity="0.35"/> <stop offset="100%" stop-color="#05070a" stop-opacity="0"/> </radialGradient> <radialGradient id="halo" cx="50%" cy="50%" r="50%"> <stop offset="0%" stop-color="#22d3ee" stop-opacity="0.12"/> <stop offset="100%" stop-color="#22d3ee" stop-opacity="0"/> </radialGradient> <filter id="glow" x="-60%" y="-60%" width="220%" height="220%"> <feGaussianBlur stdDeviation="4" result="b"/> <feMerge><feMergeNode in="b"/><feMergeNode in="SourceGraphic"/></feMerge> </filter> <pattern id="grid" width="34" height="34" patternUnits="userSpaceOnUse"> <circle cx="1" cy="1" r="1" fill="#8fb7d6" opacity="0.05"/> </pattern> </defs> <rect x="2" y="2" width="1276" height="636" rx="20" fill="url(#bg)" stroke="#1b2431" stroke-width="2"/> <rect x="2" y="2" width="1276" height="636" rx="20" fill="url(#grid)"/> <g stroke="#38bdf8" stroke-width="2.5" opacity="0.5" fill="none" stroke-linecap="round"> <path d="M36 42 h60 M40 38 v60"/> <path d="M1244 42 h-60 M1240 38 v60"/> <path d="M36 598 h60 M40 602 v-60"/> <path d="M1244 598 h-60 M1240 602 v-60"/> </g> <g><circle cx="1150" cy="62" r="7" fill="#ff5f56" filter="url(#glow)"/><text x="1168" y="68" fill="#ff8b84" font-size="18" font-weight="700" letter-spacing="2">REC</text></g> <!-- aperture-eye (reused identity, transformed to center ~280,378) --> <g transform="translate(20,170) scale(1.3)"> <circle cx="200" cy="160" r="150" fill="url(#halo)"/> <path d="M70 160 C130 92 270 92 330 160 C270 228 130 228 70 160 Z" fill="#0a1120" stroke="#38bdf8" stroke-width="3" filter="url(#glow)"/> <circle cx="200" cy="160" r="66" fill="url(#iris)"/> <circle cx="200" cy="160" r="72" fill="none" stroke="#38bdf8" stroke-width="1" opacity="0.35" stroke-dasharray="2 6"/> <circle cx="200" cy="160" r="66" fill="none" stroke="#7dd3fc" stroke-width="2.2"/> <g stroke="#38bdf8" stroke-width="1.6" opacity="0.65" stroke-linecap="round"> <line x1="228.6" y1="176.5" x2="254.6" y2="191.5"/> <line x1="200" y1="193" x2="200" y2="223"/> <line x1="171.4" y1="176.5" x2="145.4" y2="191.5"/> <line x1="171.4" y1="143.5" x2="145.4" y2="128.5"/> <line x1="200" y1="127" x2="200" y2="97"/> <line x1="228.6" y1="143.5" x2="254.6" y2="128.5"/> </g> <polygon points="238,160 219,192.9 181,192.9 162,160 181,127.1 219,127.1" fill="#05080d" stroke="#7dd3fc" stroke-width="1.5"/> <circle cx="200" cy="160" r="13" fill="#04070c"/> <circle cx="192" cy="152" r="4" fill="#d6f4ff" opacity="0.9"/> <g stroke="#f5a623" stroke-width="2.4" opacity="0.85" fill="none" stroke-linecap="round"> <path d="M96 66 h30 M96 66 v30"/> <path d="M304 66 h-30 M304 66 v30"/> <path d="M96 254 h30 M96 254 v-30"/> <path d="M304 254 h-30 M304 254 v-30"/> </g> </g> <text x="470" y="212" font-size="70" font-weight="700" letter-spacing="-1"><tspan fill="#e6edf3">claude-code-</tspan><tspan fill="#38bdf8" filter="url(#glow)">eyes</tspan></text> <rect x="474" y="234" width="176" height="4" rx="2" fill="#38bdf8" opacity="0.85"/> <rect x="658" y="234" width="88" height="4" rx="2" fill="#f5a623" opacity="0.85"/> <text x="474" y="284" font-size="26" fill="#9aa7b4">Eyes for Claude Code — the outputs no test can see.</text> <text x="474" y="372" font-size="33" font-weight="700" fill="#e6edf3">Claude Code wired up an ESP32</text> <text x="474" y="416" font-size="33" font-weight="700" fill="#e6edf3">and fixed its display — <tspan fill="#38bdf8">by looking.</tspan></text> <text x="474" y="466" font-size="23" fill="#7dd3fc">Built by a quadriplegic developer.</text> <text x="80" y="602" font-size="22" fill="#5a6672" letter-spacing="1">MIT · github.com/fcavalcantirj/claude-code-eyes</text> </svg>tests/fixture.py4.4 KB736569ace19aupstream ↗
import base64, sys, os from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer # 1x1 JPEG JPG = base64.b64decode( b"/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a" b"HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAABAAAAAAAA" b"AAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AKp//2Q==") CRED = base64.b64encode(b"user:pass").decode() class H(BaseHTTPRequestHandler): ZOOM_STEPS = list(range(100, 1001, 9)) state = {"zoom": "100"} log = [] def log_message(self, *a): pass def _img(self): self.send_response(200) self.send_header("Content-Type", "image/jpeg") self.send_header("Content-Length", str(len(JPG))) self.end_headers(); self.wfile.write(JPG) def _text(self, body, code=200): b = body.encode() self.send_response(code) self.send_header("Content-Type", "text/xml") self.send_header("Content-Length", str(len(b))) self.end_headers(); self.wfile.write(b) def do_GET(self): p = self.path.split("?")[0] q = self.path.split("?")[1] if "?" in self.path else "" # --- IP Webcam control surface (verified against a real device) ------- if p == "/status.json": zoom = H.state["zoom"] body = '{"curvals":{"zoom":"%s","focusmode":"continuous-video"}' % zoom if "show_avail=1" in q: body += ',"avail":{"zoom":[%s],"focusmode":["off","auto","macro"]}' % ( ",".join('"%d"' % v for v in H.ZOOM_STEPS)) body += "}" b = body.encode() self.send_response(200) self.send_header("Content-Type", "application/json") self.send_header("Content-Length", str(len(b))) self.end_headers(); self.wfile.write(b); return if p == "/settings/zoom": val = q.split("set=")[-1] if "set=" in q else "" if val.isdigit() and int(val) in H.ZOOM_STEPS: H.state["zoom"] = val H.log.append("zoom=%s" % val) self._text('<?xml version="1.0"?><result>Ok</result>'); return self._text('<?xml version="1.0"?><result>Fail</result>'); return if p == "/focus": H.log.append("focus") self._text('<?xml version="1.0"?><result>Ok</result>'); return if p == "/nofocus": H.log.append("nofocus") self._text('<?xml version="1.0"?><result>Ok</result>'); return if p == "/_log": # test introspection self._text("\n".join(H.log)); return if p == "/_reset": H.state["zoom"] = "100"; H.log[:] = [] self._text("ok"); return if p == "/_nozoom": # simulate a camera without zoom H.ZOOM_STEPS = [] self._text("ok"); return if p == "/html": # 200 but not an image body = b"<html><body>not an image</body></html>" self.send_response(200) self.send_header("Content-Type", "text/html") self.send_header("Content-Length", str(len(body))) self.end_headers(); self.wfile.write(body); return if p == "/forbidden": # how a proxy refuses -> curl exit 22 self.send_response(403); self.end_headers(); self.wfile.write(b"denied"); return if p == "/proxyblock": # a proxy that names its own verdict body = b"Connection blocked by network allowlist" self.send_response(403) self.send_header("X-Proxy-Error", "blocked-by-allowlist") self.send_header("Content-Length", str(len(body))) self.end_headers(); self.wfile.write(body); return if p == "/auth": got = self.headers.get("Authorization", "") if got != "Basic " + CRED: self.send_response(401) self.send_header("WWW-Authenticate", 'Basic realm="cam"') self.end_headers(); return self._img(); return self._img() # /shot.jpg, /snapshot, anything else # argv: PORT [BIND]. BIND defaults to loopback; the proxy-bypass test needs # 0.0.0.0 because curl never routes loopback through a proxy. ThreadingHTTPServer((sys.argv[2] if len(sys.argv) > 2 else "127.0.0.1", int(sys.argv[1])), H).serve_forever()tests/run_tests.sh19 KBf4c808790a88upstream ↗
#!/bin/bash # claude-code-eyes test matrix. Usage: run_tests.sh /path/to/repo REPO="${1:-$(cd "$(dirname "$0")/.." && pwd)}" SNAP="$REPO/snap.sh"; SETUP="$REPO/setup.sh" SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" BASE="http://127.0.0.1:8099" # --- fixtures: started here, stopped on exit --------------------------------- FIXTURE="$(cd "$(dirname "$0")" && pwd)/fixture.py" cleanup() { [ -n "${F1:-}" ] && kill "$F1" 2>/dev/null; [ -n "${F2:-}" ] && kill "$F2" 2>/dev/null; return 0; } trap cleanup EXIT INT TERM python3 "$FIXTURE" 8099 >/dev/null 2>&1 & F1=$! python3 "$FIXTURE" 8097 0.0.0.0 >/dev/null 2>&1 & F2=$! for _ in 1 2 3 4 5 6 7 8 9 10; do curl -s -o /dev/null -m 1 "$BASE/shot.jpg" && break sleep 0.5 done curl -s -o /dev/null -m 2 "$BASE/shot.jpg" || { echo "fixture failed to start on 8099" >&2; exit 1; } PASS=0; FAIL=0 ok(){ PASS=$((PASS+1)); printf 'PASS %s\n' "$1"; } no(){ FAIL=$((FAIL+1)); printf 'FAIL %s\n -> %s\n' "$1" "$2"; } chk(){ # name expected_exit "expected substring in output" -- cmd... local name="$1" xrc="$2" xsub="$3"; shift 3; [ "$1" = "--" ] && shift local out rc out="$("$@" 2>&1)"; rc=$? if [ "$rc" != "$xrc" ]; then no "$name" "exit $rc, wanted $xrc :: $(printf '%s' "$out"|head -2|tr '\n' '|')"; return; fi if [ -n "$xsub" ] && ! printf '%s' "$out" | grep -qF "$xsub"; then no "$name" "missing '$xsub' :: $(printf '%s' "$out"|head -3|tr '\n' '|')"; return; fi ok "$name" } newdir(){ W="$(mktemp -d)"; cd "$W" || exit 1; } echo "=== syntax ===" bash -n "$SNAP" && ok "snap.sh parses" || no "snap.sh parses" "syntax error" bash -n "$SETUP" && ok "setup.sh parses" || no "setup.sh parses" "syntax error" echo "=== existing matrix ===" newdir chk "no config -> exit 1" 1 "no CCE_CAM_URL" -- \ env -u CCE_CAM_URL -u CCE_CAM_TYPE -u CCE_OUT_DIR HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" chk "unknown type -> exit 2" 2 "unknown CCE_CAM_TYPE" -- \ env CCE_CAM_TYPE=bogus CCE_CAM_URL="$BASE" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" chk "bad count -> exit 2" 2 "count must be" -- \ env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" abc # backend: url newdir out="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" if [ -f "$out" ] && [ "$(file --mime-type -b "$out")" = "image/jpeg" ]; then ok "backend url -> jpeg"; else no "backend url -> jpeg" "$out"; fi # backend: ipwebcam (/shot.jpg) newdir out="$(env CCE_CAM_TYPE=ipwebcam CCE_CAM_URL="$BASE" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" if [ -f "$out" ]; then ok "backend ipwebcam"; else no "backend ipwebcam" "$out"; fi # backend: camera-streamer (/snapshot) newdir out="$(env CCE_CAM_TYPE=camera-streamer CCE_CAM_URL="$BASE" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" if [ -f "$out" ]; then ok "backend camera-streamer"; else no "backend camera-streamer" "$out"; fi # watch mode newdir n="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 3 1 2>/dev/null | wc -l | tr -d ' ')" [ "$n" = "3" ] && ok "watch mode 3 frames" || no "watch mode 3 frames" "got $n lines" # non-image guard newdir chk "html 200 rejected (exit 1, msg names non-image)" 1 "non-image content" -- \ env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/html" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" # basic auth newdir out="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/auth" CCE_CAM_AUTH="user:pass" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" [ -f "$out" ] && ok "basic auth ok" || no "basic auth ok" "$out" newdir chk "basic auth wrong -> exit 1" 1 "" -- \ env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/auth" CCE_CAM_AUTH="user:nope" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" # env beats .cce.env newdir printf 'CCE_CAM_URL=%s/html\nCCE_CAM_TYPE=url\n' "$BASE" > .cce.env out="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" [ -f "$out" ] && ok "env beats .cce.env" || no "env beats .cce.env" "$out" # .cce.env used when env empty newdir printf 'CCE_CAM_URL=%s/shot.jpg\nCCE_CAM_TYPE=url\n' "$BASE" > .cce.env out="$(env -u CCE_CAM_URL -u CCE_CAM_TYPE HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" [ -f "$out" ] && ok ".cce.env is read" || no ".cce.env is read" "$out" echo "=== new: output dir ===" newdir out="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" case "$out" in "$W/.claude-code-eyes/"*) ok "default out dir = CWD/.claude-code-eyes";; *) no "default out dir = CWD/.claude-code-eyes" "$out";; esac newdir out="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" CCE_OUT_DIR="$W/custom" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" case "$out" in "$W/custom/"*) ok "CCE_OUT_DIR env override";; *) no "CCE_OUT_DIR env override" "$out";; esac newdir printf 'CCE_OUT_DIR=%s/fromfile\n' "$W" > .cce.env out="$(env -u CCE_OUT_DIR CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" case "$out" in "$W/fromfile/"*) ok "CCE_OUT_DIR from .cce.env";; *) no "CCE_OUT_DIR from .cce.env" "$out";; esac echo "=== new: allowlist boundary still holds ===" newdir printf 'EVIL=pwned\nPATH=/nope\nCCE_CAM_URL=%s/shot.jpg\nCCE_CAM_TYPE=url\n' "$BASE" > .cce.env out="$(env -u CCE_CAM_URL -u CCE_CAM_TYPE HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" if [ -f "$out" ]; then ok "non-allowlisted keys ignored (EVIL/PATH)"; else no "non-allowlisted keys ignored" "$out"; fi echo "=== new: failure diagnosis ===" PX="HTTP_PROXY=http://127.0.0.1:1" # stand-in for the proxy the sandbox always sets # 403 behind a proxy == how the sandbox refuses an unlisted address newdir o="$(env $PX CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/forbidden" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)"; rc=$? if [ "$rc" = 1 ] && printf '%s' "$o" | grep -qF "answered 403 Forbidden" \ && printf '%s' "$o" | grep -qF "\"excludedCommands\": [\"bash $SNAP\"]" \ && ! printf '%s' "$o" | grep -qF '"allowedDomains": ['; then ok "403 + proxy on a LAN host -> excludedCommands (never an allowedDomains snippet)" else no "403 + proxy LAN host" "rc=$rc :: $(printf '%s' "$o"|tr '\n' '|')"; fi # 403 with NO proxy is the camera's own answer, not a sandbox verdict newdir o="$(env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY -u http_proxy -u https_proxy -u all_proxy \ CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/forbidden" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)"; rc=$? if [ "$rc" = 1 ] && printf '%s' "$o" | grep -qF "this 403 came from the camera" \ && ! printf '%s' "$o" | grep -qF "sandbox"; then ok "403 without proxy -> blamed on the camera, no sandbox claim" else no "403 without proxy" "rc=$rc :: $(printf '%s' "$o"|tr '\n' '|')"; fi # THE REGRESSION THAT MATTERED: a sleeping camera behind the sandbox proxy is # NOT a sandbox denial. Measured: allow-listed-but-down => curl 7 / status 000. newdir o="$(env $PX CCE_CAM_TYPE=url CCE_CAM_URL="http://127.0.0.1:9/x.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)"; rc=$? if [ "$rc" = 1 ] && printf '%s' "$o" | grep -qF "camera not reachable" \ && ! printf '%s' "$o" | grep -qF "refused with 403"; then ok "unreachable + proxy -> unreachable (NOT a sandbox verdict)" else no "unreachable + proxy misreported as sandbox" "rc=$rc :: $(printf '%s' "$o"|tr '\n' '|')"; fi if printf '%s' "$o" | grep -qF "This shell is sandboxed" \ && printf '%s' "$o" | grep -qF "\"excludedCommands\": [\"bash $SNAP\"]"; then ok "unreachable + proxy hints at sandbox with the LAN-correct remedy" else no "unreachable + proxy hint" "$(printf '%s' "$o"|tr '\n' '|')"; fi # 401 names the auth key rather than blaming the network newdir o="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/auth" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)"; rc=$? if [ "$rc" = 1 ] && printf '%s' "$o" | grep -qF "401 Unauthorized" \ && printf '%s' "$o" | grep -qF "CCE_CAM_AUTH"; then ok "401 -> auth message naming CCE_CAM_AUTH" else no "401 -> auth message" "rc=$rc :: $(printf '%s' "$o"|tr '\n' '|')"; fi # an HTTP answer is an answer: do not burn retries on it newdir t0=$(date +%s) env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/forbidden" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" >/dev/null 2>&1 t1=$(date +%s) if [ $((t1-t0)) -le 2 ]; then ok "HTTP status is not retried (fast fail)"; else no "HTTP status not retried" "took $((t1-t0))s"; fi echo "=== new: retry survives a late-starting camera ===" newdir ( sleep 1.5; exec python3 "$FIXTURE" 8098 >/dev/null 2>&1 ) & LATE=$! # exec => $LATE is the server itself, killable even if snap.sh gave up early o="$(env CCE_CAM_TYPE=url CCE_CAM_URL="http://127.0.0.1:8098/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)"; rc=$? if [ "$rc" = 0 ] && [ -f "$o" ]; then ok "retry recovers a camera that refuses at first"; else no "retry recovers late camera" "rc=$rc :: $o"; fi kill $LATE 2>/dev/null; pkill -f "fixture.py 8098" 2>/dev/null; wait $LATE 2>/dev/null echo "=== new: the exclusion entry must match how snap.sh is ACTUALLY invoked ===" # Claude Code matches excludedCommands with: # prefix: t === prefix || t.startsWith(prefix + " ") exact: t === command # SKILL.md documents `bash <path-to-skill>/snap.sh`, so a bare "bash snap.sh" # entry can never match a real invocation. The entry must carry snap.sh's own # absolute path -- which as a prefix also covers watch mode (`... snap.sh 3 2`). PX="HTTP_PROXY=http://127.0.0.1:1" newdir # cwd is a temp dir, NOT the skill dir o="$(env $PX CCE_CAM_TYPE=url CCE_CAM_URL="http://127.0.0.1:9/x.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" if printf '%s' "$o" | grep -qF "\"excludedCommands\": [\"bash $SNAP\"]"; then ok "snap.sh advises its own absolute path" else no "snap.sh advises its own absolute path" "$(printf '%s' "$o"|grep -i excluded|tr '\n' '|')"; fi if printf '%s' "$o" | grep -qF '["bash snap.sh"]'; then no "snap.sh must not advise the unmatchable relative literal" "still prints [\"bash snap.sh\"]" else ok "snap.sh drops the unmatchable relative literal"; fi # watch-mode args are covered by prefix matching, so the entry must have no args if printf '%s' "$o" | grep -qE '"excludedCommands": \["bash [^"]*snap\.sh"\]'; then ok "exclusion entry carries no trailing args (prefix covers watch mode)" else no "exclusion entry shape" "$(printf '%s' "$o"|grep -i excluded|tr '\n' '|')"; fi # the zero-config escape hatch should be mentioned before the settings edit if printf '%s' "$o" | grep -qiF "outside the sandbox" ; then ok "sandbox message mentions the unsandboxed-retry escape hatch" else no "escape hatch mentioned" "$(printf '%s' "$o"|tr '\n' '|')"; fi echo "=== new: CRLF (the bug that actually killed a real install) ===" # Field report 2026-08-20: a Windows-saved copy had CRLF terminators and bash died at # `set -euo pipefail` with "set: pipefail: invalid option name" before any camera # contact. git's core.autocrlf defaults to true on Windows, so a clone can reintroduce # it -- .gitattributes is what stops that at distribution time. if [ -f "$REPO/.gitattributes" ]; then ok ".gitattributes exists"; else no ".gitattributes exists" "missing"; fi eolattr="$(cd "$REPO" && git check-attr eol -- snap.sh 2>/dev/null | sed 's/.*: //')" if [ "$eolattr" = "lf" ]; then ok "git pins snap.sh to eol=lf"; else no "git pins snap.sh to eol=lf" "got '$eolattr'"; fi eolattr2="$(cd "$REPO" && git check-attr eol -- setup.sh 2>/dev/null | sed 's/.*: //')" if [ "$eolattr2" = "lf" ]; then ok "git pins setup.sh to eol=lf"; else no "git pins setup.sh to eol=lf" "got '$eolattr2'"; fi # shipped files must be CR-free right now crs="$(tr -cd '\r' < "$REPO/snap.sh" | wc -c | tr -d ' ')" if [ "$crs" = "0" ]; then ok "shipped snap.sh has no CR bytes"; else no "snap.sh CR-free" "$crs CR bytes"; fi # reproduce the reported failure, so we know the symptom is real newdir sed 's/$/\r/' "$SNAP" > ./crlf_snap.sh crlf_err="$(bash ./crlf_snap.sh 2>&1 | head -3)" if printf '%s' "$crlf_err" | grep -qF "pipefail"; then ok "CRLF copy reproduces the reported 'set: pipefail' death" else no "CRLF repro" "$(printf '%s' "$crlf_err"|tr '\n' '|')"; fi # setup.sh must catch it, because snap.sh cannot self-diagnose (bash dies first) newdir mkdir -p kit && sed 's/$/\r/' "$SNAP" > kit/snap.sh && cp "$SETUP" kit/setup.sh o="$(HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash kit/setup.sh --url "$BASE" --type ipwebcam 2>&1)" if printf '%s' "$o" | grep -qiF "CRLF"; then ok "setup.sh detects CRLF in snap.sh and says so" else no "setup.sh detects CRLF" "$(printf '%s' "$o"|tr '\n' '|'|head -c 300)"; fi echo "=== new: a 403 must not be blamed on the Bash sandbox alone ===" # Field report: the 403 came from a Cowork device-bridge egress proxy answering # X-Proxy-Error: blocked-by-allowlist -- not from Claude Code's sandbox. newdir o="$(env HTTP_PROXY=http://127.0.0.1:1 CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/proxyblock" \ HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)" if printf '%s' "$o" | grep -qF "blocked-by-allowlist"; then ok "403: echoes the proxy's own X-Proxy-Error verdict" else no "403 echoes X-Proxy-Error" "$(printf '%s' "$o"|tr '\n' '|'|head -c 300)"; fi if printf '%s' "$o" | grep -qiF "which is how the Claude Code Bash sandbox blocks"; then no "403 must not assert the sandbox as the sole cause" "still asserts it" else ok "403 does not assert the sandbox as the sole cause"; fi echo "=== new: zoom + focus (issue #1) ===" # Verified against a real IP Webcam device 2026-08-20: # /settings/zoom?set=V absolute, V from avail.zoom (100=1x .. 1000=max) # /ptz?zoom=P PERCENT 0..100 -- NOT absolute (this is the trap) # /focus, /nofocus momentary trigger # curvals.zoom LAGS several seconds behind the set # pydroid-ipcam's /settings/ptz?zoom=N is a 404 on the device; do not use it. RESET(){ curl -s -m 5 "$BASE/_reset" >/dev/null 2>&1; } LOG(){ curl -s -m 5 "$BASE/_log" 2>/dev/null; } RESET; newdir out="$(env CCE_CAM_TYPE=ipwebcam CCE_CAM_URL="$BASE" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" --zoom 3 2>/dev/null)" if [ -f "$out" ]; then ok "--zoom captures a frame"; else no "--zoom captures a frame" "[$out]"; fi l="$(LOG)" if printf '%s' "$l" | grep -qE "^zoom=(298|307)$"; then ok "--zoom 3 maps to ~300 device units and snaps to an allowed step" else no "--zoom 3 maps to device units" "log=[$(printf '%s' "$l"|tr '\n' ' ')]"; fi if [ "$(printf '%s' "$l" | tail -1)" = "zoom=100" ]; then ok "zoom is RESTORED after capture (camera not left zoomed)" else no "zoom restored after capture" "log ends [$(printf '%s' "$l"|tail -1)]"; fi RESET; newdir out="$(env CCE_CAM_TYPE=ipwebcam CCE_CAM_URL="$BASE" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" --focus 2>/dev/null)" if [ -f "$out" ] && printf '%s' "$(LOG)" | grep -q "^focus$"; then ok "--focus triggers /focus then captures" else no "--focus triggers /focus" "out=$out log=[$(LOG|tr '\n' ' ')]"; fi RESET; newdir out="$(env CCE_CAM_TYPE=ipwebcam CCE_CAM_URL="$BASE" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" --zoom 5 2 1 2>/dev/null)" n="$(printf '%s\n' "$out" | grep -c "\.jpg$")" if [ "$n" = "2" ]; then ok "--zoom composes with watch mode (2 frames)"; else no "--zoom + watch mode" "got $n frames"; fi if [ "$(LOG | tail -1)" = "zoom=100" ]; then ok "zoom restored after watch mode too"; else no "zoom restored after watch" "$(LOG|tail -1)"; fi RESET; newdir # unsupported backend must NOT fail the capture out="$(env CCE_CAM_TYPE=url CCE_CAM_URL="$BASE/shot.jpg" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" --zoom 3 2>&1)"; rc=$? if [ "$rc" = 0 ] && printf '%s' "$out" | grep -qi "zoom"; then ok "url backend: says it cannot zoom, still captures, exit 0" else no "url backend graceful" "rc=$rc :: $(printf '%s' "$out"|tr '\n' '|')"; fi RESET; newdir # a bad zoom argument is rejected, not sent blind o="$(env CCE_CAM_TYPE=ipwebcam CCE_CAM_URL="$BASE" HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" --zoom 99 2>&1)"; rc=$? if [ "$rc" = 2 ]; then ok "--zoom out of range -> exit 2"; else no "--zoom range check" "rc=$rc :: $(printf '%s' "$o"|head -1)"; fi echo "=== new: a LAN camera must never be sent through a proxy ===" # Field report 2026-08-20: an egress proxy refused the camera's LAN IP. no_proxy was # set to 192.168.0.0/16 but their curl could not CIDR-match it (CIDR support landed # in curl 7.86), so the bypass silently did nothing. Passing --noproxy <host> # explicitly works on every curl version and regardless of no_proxy spelling. # NOTE: curl never proxies loopback, so this must be tested on a real LAN address. LANIP="$(ipconfig getifaddr en0 2>/dev/null || hostname -I 2>/dev/null | awk '{print $1}')" if [ -z "$LANIP" ] || ! curl -s -o /dev/null -m 3 "http://$LANIP:8097/shot.jpg"; then echo "SKIP LAN-proxy tests (no LAN fixture on $LANIP:8097)" else newdir out="$(env http_proxy=http://127.0.0.1:1 ALL_PROXY=http://127.0.0.1:1 \ CCE_CAM_TYPE=url CCE_CAM_URL="http://$LANIP:8097/shot.jpg" \ HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>/dev/null)" if [ -f "$out" ]; then ok "LAN camera captured despite a dead proxy in the env" else no "LAN camera bypasses the proxy" "no frame; proxy was not bypassed"; fi # a PUBLIC host must still honour the proxy -- bypassing it there would break # anyone whose only route out is the proxy newdir o="$(env http_proxy=http://127.0.0.1:1 ALL_PROXY=http://127.0.0.1:1 \ CCE_CAM_TYPE=url CCE_CAM_URL="http://example.com/shot.jpg" \ HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SNAP" 2>&1)"; rc=$? if [ "$rc" != 0 ]; then ok "public host still routed via the proxy (not bypassed)" else no "public host must not bypass the proxy" "unexpectedly succeeded"; fi fi echo "=== setup.sh ===" newdir o="$(HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SETUP" --url "$BASE" --type ipwebcam 2>&1)"; rc=$? if [ "$rc" = 0 ] && printf '%s' "$o" | grep -qF "got a live frame" \ && printf '%s' "$o" | grep -qF "\"excludedCommands\": [\"bash $SNAP\"]" \ && [ -f "$W/cfg/claude-code-eyes/config" ]; then ok "setup --url (LAN) advises the absolute path of its sibling snap.sh" else no "setup --url writes+verifies" "rc=$rc :: $(printf '%s' "$o"|tr '\n' '|')"; fi newdir o="$(HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SETUP" --url "http://192.0.2.7:8080" --type ipwebcam 2>&1)"; rc=$? if [ "$rc" = 0 ] && [ -f "$W/cfg/claude-code-eyes/config" ] \ && printf '%s' "$o" | grep -qF "config is saved and correct" \ && printf '%s' "$o" | grep -qF '"allowedDomains": ["192.0.2.7:8080"]'; then ok "setup dead PUBLIC camera: exit 0, config saved, allowedDomains hint" else no "setup dead camera exit 0" "rc=$rc :: $(printf '%s' "$o"|tr '\n' '|')"; fi newdir o="$(HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SETUP" --url "http://192.168.7.7:8080" --type ipwebcam 2>&1)" if printf '%s' "$o" | grep -qF "\"excludedCommands\": [\"bash $SNAP\"]" \ && ! printf '%s' "$o" | grep -qF '"allowedDomains": ['; then ok "setup LAN camera advises excludedCommands, never an allowedDomains snippet" else no "setup LAN advice" "$(printf '%s' "$o"|tr '\n' '|')"; fi newdir o="$(HOME="$W" XDG_CONFIG_HOME="$W/cfg" bash "$SETUP" --local --url "$BASE" --type ipwebcam 2>&1)" if [ -f "$W/.cce.env" ]; then ok "setup --local writes ./.cce.env"; else no "setup --local" "$o"; fi echo echo "PASS=$PASS FAIL=$FAIL" [ "$FAIL" -eq 0 ]
Plain-text copy, no login: /skill-bundles/fcavalcantirj-claude-code-eyes.md