# claude-code-eyes

Adopt this skill: https://proskills.md/skills/other/fcavalcantirj-claude-code-eyes

Page: https://proskills.md/skills/other/fcavalcantirj-claude-code-eyes
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8095
sha: e8ccea585ccc885ca0f0cbc55137f9769f84a108
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/SKILL.md

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

## File: README.md
size: 20245
sha: 838db3c79f4711f47e7d02d0a37fe5c2d468eeb0
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/README.md

````text
<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).
````

## File: tests/README.md
size: 1745
sha: 6ab22308bedc35930ead6b1b71187a354a0cadb6
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/tests/README.md

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

## File: .gitattributes
size: 613
sha: 28ceab151400a9852284580c323d243b5800f2fa
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/.gitattributes

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

## File: .gitignore
size: 333
sha: 10f3516b5b907efc7157657d870c270a90c16425
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/.gitignore

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

## File: banner.svg
size: 5014
sha: 0e8245bd738cb95dac057f5328257471e87b8018
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/banner.svg

```text
<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 &#183; verify wiring before power-on.</text>
  <text x="382" y="270" font-size="15" fill="#4d5a68" letter-spacing="0.5">IP&#8202;Webcam &#183; camera-streamer &#183; any snapshot URL</text>

  <!-- easter egg: the bug only eyes caught -->
  <text x="1018" y="236" font-size="11" fill="#56606a">&#9666; 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 &#183; /shot.jpg &#183; image/jpeg &#183; snapshot</text>
</svg>
```

## File: CLAUDE.md
size: 4409
sha: 24da1cf61326faaa712130ab3f8b9b2c000f24ef
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/CLAUDE.md

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

## File: demo.gif
size: 7426147
sha: 66c2b6a797305c5e32cfdece9dc747a92268a742
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/demo.gif

Content is not inlined in the catalog. Read the upstream file: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/demo.gif

## File: evals/evals.json
size: 1314
sha: 7a70fcd406b766497109fce92dbe734ae2127aef
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/evals/evals.json

```text
[
  { "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 }
]
```

## File: LICENSE
size: 1074
sha: 319c4d2bd7055cd74af33b688903969a31db6e57
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/LICENSE

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

## File: setup.sh
size: 9784
sha: 3d1c67cb955bef888a9c930586f440bba8cd8e81
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/setup.sh

```text
#!/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:p@1.2.3.4: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"
```

## File: snap.sh
size: 18062
sha: 79b38c81688c787e4a49d5b3abb09e4b1a7cb2ca
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/snap.sh

```text
#!/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:p@1.2.3.4: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 0
```

## File: social-card.png
size: 174894
sha: ff39c89506e67a55bcde6b54320cb0b778af8e84
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/social-card.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/social-card.png

## File: social-card.svg
size: 4395
sha: b24a966f3b166b47aa80f244e4e5f9fd3c6318ae
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/social-card.svg

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

## File: tests/fixture.py
size: 4468
sha: 736569ace19a8e73c6c8781f760fd52bdc6c09fd
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/tests/fixture.py

```text
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()
```

## File: tests/run_tests.sh
size: 19518
sha: f4c808790a88fa9ec4377e47e51cb591c2b924ec
upstream: https://github.com/fcavalcantirj/claude-code-eyes/blob/HEAD/tests/run_tests.sh

```text
#!/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 ]
```
