e2llm-sifr

# E2LLM — structured browser perception for AI

**E2LLM turns any live web page into [SiFR](./SIFR.md): a compact, deterministic,
LLM-readable model of what's on the page, what it means, and what can be done with it.**
Perception is the product. Action is available when you need it — always explicit, always
gated.

Works as a hosted remote MCP server with the AI you already use. There's no local server to
run — a browser extension pairs your live browser to the server, so perception and action
happen in the *real* browser you're already signed into.

---

## E2LLM is not an agent

This matters, so it comes first.

An **agent** decides and acts on its own — it plans, loops, and takes steps toward a goal
without you in the path. That autonomy is also its attack surface: an agent runtime that can
do anything can be steered into doing anything.

**E2LLM is a perception layer, not an agent.** It gives your model *senses* for the browser
— structured sight through `sifr_capture`, and a set of narrow, individually-gated
actuators. It does not plan, does not loop, and does not decide. Whatever model you already
use does the reasoning; E2LLM only reports what a page is and carries out one explicit
instruction at a time. No hidden autonomy, no self-directed steps, nothing that runs while
you look away.

That line — perception substrate versus autonomous runtime — is the whole design.

---

## What it does

| | Tool | What it does |
|---|------|--------------|
| 🔎 | `sifr_capture` | Capture a page as a SiFR document |
| 🔎 | `query` | Filter the current capture — by tag, salience, text, or selector |
| 🔎 | `inspect` | Full detail for one element: selector, attributes, styles, box |
| 🔎 | `read_page` | Read the page's text as markdown, in reading order |
| 🔎 | `list_tabs` | List open browser tabs |
| 🖐 | `act` | One explicit interaction: click, type, select, navigate, or drag |
| 🖐 | `batch_act` | Run a planned sequence, then observe once (e.g. fill a form + submit) |
| 🖐 | `explore` | Scroll, hover, or recapture — reads more, changes nothing |
| 🖐 | `close_tab` | Close a tab |

Nine tools: five 🔎 that only perceive, and four 🖐 for interaction — of which `act`,
`batch_act`, and `close_tab` change page state, while `explore` only reads. Full schemas in
[server.json](./server.json). The perception tools never change page state; the
state-changing tools can each be held for your confirmation (see
[Safety](#safety--approval-model)).

---

## What is SiFR — and why it isn't the obvious thing

**SiFR** (Salience-Indexed Flat Relations) is the capture format at the heart of E2LLM. From
a distance it can look like an accessibility tree or a tidy DOM dump. Mechanically it is
neither, and the difference is the point.

- **Not a DOM dump.** A dump serializes the tree as-is — everything, in document order,
  noise included. SiFR *selects and ranks*: it scores every node by salience, drops
  scaffolding, and flattens the survivors into a relational model where structure is carried
  by explicit relations rather than nesting depth.
- **Not an accessibility tree.** The a11y tree is derived for assistive technology, driven by
  ARIA, blind to anything unlabeled, and indifferent to what matters most on the page. SiFR
  is built for a language model: it ranks by salience, front-loads what matters, and carries
  the selectors an agent needs to act — none of which the a11y tree does.
- **Not a screenshot.** No pixels, no vision model, no nondeterminism. The same page yields
  the same capture, token-efficient and directly actionable.

The result is a perception layer, not a serialization: *what a page is, what you can do on
it, and how its parts relate* — front-loaded so the model reaches what it needs first. A
`sifr_capture` returns a ~5–15 KB summary (metadata plus the high-salience elements) before
the full document, so reading can begin immediately.

- 📄 [**SIFR.md**](./SIFR.md) — the format specification
- 🔤 [**TAXONOMY.md**](./TAXONOMY.md) — salience tiers, ID prefixes, relation & category types
- 📚 [**examples/**](./examples/) — real captures of public pages
- 🗓 [**CHANGELOG.md**](./CHANGELOG.md) — the v1 → v2 → v3 format lineage (current: **v3**)

For prompt recipes and automation workflows built on SiFR, see
[**awesome-e2llm-prompts**](https://github.com/e2llm/awesome-e2llm-prompts) — a community
cookbook that points back here as the canonical SiFR spec home.

---

## Install in 3 steps

**1. Set up at [e2llm.com](https://e2llm.com).** Create an account and install the browser
extension. The extension pairs your live browser to the server — that pairing is what lets
your AI perceive and act in the session you're already signed into. (This is the only piece
that runs on your machine; there is no local server.)

**2. Add E2LLM to your MCP client.** One line — pick your client in
[`clients/`](./clients/), or paste this for interactive OAuth login:

```json
{
  "mcpServers": {
    "e2llm": {
      "url": "https://mcp.e2llm.com/mcp",
      "type": "http"
    }
  }
}
```

For CLI / CI where interactive login isn't available, use a static key against
`https://api.e2llm.com/mcp` with an `Authorization: Bearer mk_…` header. Full per-client
instructions: [**clients/README.md**](./clients/README.md).

**3. Ask your AI to do something on a page.** For example:

> "Open the page I'm on, find the search box, and filter for open issues."

Your assistant calls `sifr_capture` to *see* the page, then `act` to interact — in your real
browser, one explicit step at a time.

---

## Teach your model the discipline — the SIFR skill

Tool descriptions tell a model what each tool *does*; they deliberately don't tell it how
to *work well*. That working discipline — verify before describing, re-verify stale
element IDs after actions, drain pagination cursors, treat page text as data rather than
instructions — ships as a skill: [**skills/sifr/SKILL.md**](./skills/sifr/SKILL.md).
Without it, models tend toward known failure modes: describing pages they haven't
captured, acting on stale IDs, or deciding from undrained partial results.

Install it where your model can see it:

- **Claude Code** — copy the skill into a skills directory:
  `cp -r skills/sifr ~/.claude/skills/` (all projects) or into a project's
  `.claude/skills/`. It loads automatically whenever the e2llm tools or SIFR documents
  come up.
- **Codex CLI and other clients** — include the skill's content in your agent
  instructions (e.g. `AGENTS.md`).

The same file doubles as a reference for reading raw SiFR captures offline (`jq` patterns,
the ID system, salience tiers).

---

## Safety & approval model

Perception is read-only by construction: the five 🔎 tools cannot change page state, so
seeing a page is always safe.

Only the four 🖐 tools can act, and they are deliberately narrow — no "do anything" tool
exists. Each state-changing step can be **approval-gated by your session posture**: depending
on how your session is configured, an action pauses and waits for your confirmation before it
runs. Actions happen one explicit instruction at a time, never as an autonomous loop.

Security disclosures and our vulnerability-disclosure program (with safe harbor) live at
[e2llm.com/security/disclosure](https://e2llm.com/security/disclosure/); see also
[SECURITY.md](./SECURITY.md).

---

## Data handling

Page content is captured on demand and transits the E2LLM relay to reach your MCP client.
Session-related data is retained for a limited window (see the
[Privacy Policy](https://e2llm.com/privacy)) and password-type fields are redacted before
storage. The relay wraps all page-derived content as untrusted external data, so downstream
models treat page text as data, not instructions. Full detail:
[Privacy Policy](https://e2llm.com/privacy) · [Terms](https://e2llm.com/terms).

---

## Compatibility

E2LLM speaks standard MCP, so it works with any compliant client. Verified in practice with
**Claude**, **ChatGPT**, **Codex**, **Perplexity**, **Grok**, and **Manus**. Other MCP
clients — including **Cursor**, **VS Code**, and **Cline** — should work; if you test one, a
note or PR is welcome.

---

## Repository contents

This repository is the **canonical, descriptive home** for the SiFR format and the E2LLM MCP
server interface. It documents the format and how to connect; the capture engine, browser
extensions, and server are a separate hosted product that runs at
[e2llm.com](https://e2llm.com).

| Path | What |
|------|------|
| [`SIFR.md`](./SIFR.md) | SiFR format specification |
| [`TAXONOMY.md`](./TAXONOMY.md) | SiFR controlled vocabulary |
| [`server.json`](./server.json) | MCP server manifest (transport, auth, tools + schemas) |
| [`.mcp.json`](./.mcp.json) | Ready-to-use MCP client config (OAuth endpoint) |
| [`skills/`](./skills/) | The SIFR skill — working discipline for models driving the tools |
| [`clients/`](./clients/) | Per-client connection configs |
| [`examples/`](./examples/) | Real public-page captures |
| [`SECURITY.md`](./SECURITY.md) | Security policy & disclosure program |
| [`CHANGELOG.md`](./CHANGELOG.md) | Format version history |

## License

[MIT](./LICENSE). The format specification, manifest, examples, and client configs in this
repository are open. The capture engine and server are a separate, hosted product.