# anylens

**Any link, any lens.** Paste a URL — a conference talk, a product demo, a
dense PDF, an article — and get it back as understanding shaped for who's
asking, with every claim linked to the exact second or page it came from.

Agents can read text. anylens lets them read everything else — and lets you
check their work.

```
analyze(url)  →  one cached Understanding  →  lens(source, "student")
                                           →  lens(source, "spec")
                                           →  lens(source, "uiux")   …
```

## Why not just ask a chatbot to summarize it?

A summary is a dead end. You can't verify it, you can't get a different cut of
it without paying for it again, it's blind to what was on screen, and no agent
can act on it. anylens fixes those four things:

- **Verifiable** — every claim carries its timestamp or page. `stated` is never
  blurred with `inferred`. Missing analysis is named, not hidden.
- **Many readers, one extraction** — the expensive pass runs once and is cached
  forever; a second lens is cheap and instant.
- **Reads what was *shown*** — on-screen code, slides, UI states, demos, not
  just the words. A silent ten-second screen recording still produces a full
  analysis.
- **Built for agents too** — the `spec` lens turns any source into
  implementable requirements with acceptance criteria, over MCP.
- **Knows how it was made** — for video, a production pass captures the music,
  the sound design, the shot rhythm, the motion and typography, and turns it
  into a recipe you (or a generator) can rebuild from. Content lenses let an
  agent *know*; the `blueprint` lens lets it *make*.

## Lenses

| Lens | For | Gives you |
|---|---|---|
| `student` | learning without watching | layered explainer, concept map, flashcards |
| `developer` | building from it | code shown on screen, decisions, implementation steps |
| `uiux` | design study | screens, flows, interaction patterns |
| `researcher` | citable notes | claims + evidence, every one anchored |
| `teardown` | competitive analysis | features (shown vs claimed), flows, positioning |
| `spec` | **coding agents** | requirements, acceptance criteria, ambiguities |
| `blueprint` | remaking it | music, sound design, shot rhythm, motion, typography — as a production recipe |
| `design` | "make it look like this" | measured colour tokens, spacing and type rhythm, components — as paste-ready CSS |
| `ask` | one specific question | an anchored answer — or an honest "the source doesn't answer this" |
| `raw` | agents, debugging | the Understanding Object itself — no LLM, no cost |

Lenses are single markdown files in `src/lenses/`. Adding one is adding a
file — no code.

Beyond lenses: anylens can learn a reusable **style** from analyzed videos —
the pacing, structure, look, motion, and sound as portable rules, every rule
carrying the timestamp it was learned from — then plan new work in that style
(`style_extract` / `style_apply` over MCP, or "Learn this style" in the web UI).

## Quickstart

**Prerequisites**: [Bun](https://bun.sh) 1.3+, `yt-dlp`, and `ffmpeg`
(`brew install yt-dlp ffmpeg` on macOS).

```sh
git clone https://github.com/Slowper/anylens && cd anylens
bun install
```

**Keys** — run `bun run web` and paste them on the **Your keys** page (they're
validated as you save), or create `~/.anylens/env` (mode 600) yourself:

```
GOOGLE_API_KEY=...      # required: analysis, structuring, lens rendering
GROQ_API_KEY=...        # optional: Whisper transcripts for sources without captions
ANTHROPIC_API_KEY=...   # optional: run the writing on Claude instead
OPENAI_API_KEY=...      # optional: run the writing on an OpenAI model instead
```

Get them at [aistudio.google.com](https://aistudio.google.com/apikey) and
[console.groq.com](https://console.groq.com/keys). Nothing leaves your machine
except the calls you make to those APIs. The text layer is provider-agnostic:
set `ANYLENS_TEXT_MODEL=anthropic` (or `groq`, or `openai/<model>`) to choose
who writes the lenses and answers — the media passes stay on Gemini, which is
what it's genuinely best at.

**Try it** — from the terminal:

```sh
bun bin/anylens.ts "https://www.youtube.com/watch?v=..."              # student explainer
bun bin/anylens.ts ./screenshot.png --lens design --export css        # tokens you can paste
bun bin/anylens.ts ~/Desktop/demo.mov --lens blueprint                # files on your machine work too
bun bin/anylens.ts "<url>" --lens spec                                # any lens
bun bin/anylens.ts "<url>" --ask "does this cover error handling?"    # one anchored answer
bun bin/anylens.ts "<url>" --clip "where they demo the CLI"           # cut that segment to mp4
bun bin/anylens.ts "<url>" --export anki                              # flashcard deck (or markdown/json/html)
bun bin/anylens.ts "<url>" --audio                                    # narrate it to an mp3
bun bin/anylens.ts "<url>" --open                                     # render the page and open it
```

Analysis takes a few minutes the first time and is cached forever after, so
every later lens on the same link returns instantly. Pass a `source_id`
instead of a URL to re-lens something already analyzed.

Or use the web UI:

```sh
bun run web        # → http://127.0.0.1:4517 — paste a link, pick a lens
```

## Use it from an agent — any MCP client

anylens speaks standard MCP over stdio, so Claude Code, Codex, Cursor, Gemini
CLI, and anything else MCP-capable can use it the same way.

```sh
# Claude Code
claude mcp add --scope user anylens -- bun /absolute/path/to/anylens/bin/anylens.ts mcp
```

```toml
# Codex CLI — ~/.codex/config.toml
[mcp_servers.anylens]
command = "bun"
args = ["/absolute/path/to/anylens/bin/anylens.ts", "mcp"]
```

```json
// Gemini CLI (~/.gemini/settings.json), Cursor (~/.cursor/mcp.json), or any other client
{ "mcpServers": { "anylens": { "command": "bun", "args": ["/absolute/path/to/anylens/bin/anylens.ts", "mcp"] } } }
```

Once published to npm, `npx anylens mcp` replaces the path form everywhere.

Tools: `analyze(url)` → `status(job_id)` → `lens(source_id, lens)` ·
`ask(source_id, question)` · `clip(source_id, query)` ·
`export(source_id, format)` · `audio(source_id)` ·
`style_extract` / `style_apply` / `style_list` · `lenses()`.
`lens` returns `{ data, markdown }` —
typed JSON for the agent, readable markdown for the human, plus a full HTML
page with `include_html`. `ask` answers from the cache without re-analyzing.

## What it reads

Video (YouTube, X, LinkedIn, Vimeo, Twitch, Loom, direct files — anything
`yt-dlp` reaches), audio, PDFs (including scanned and figure-heavy ones, read
page by page with vision), web articles, and images.

Full inventory: [docs/FEATURES.md](docs/FEATURES.md) ·
Where it's going: [docs/ROADMAP.md](docs/ROADMAP.md) ·
Architecture and invariants: [AI_INDEX.md](AI_INDEX.md)

## Contributing

New lenses are the easiest and most valuable contribution — see
[CONTRIBUTING.md](CONTRIBUTING.md). The codebase is deliberately small files
with one concern each, so a change rarely touches more than one place.

MIT licensed.