# Visual Intent Layer

Point at a browser-rendered interface, describe what should change, and let an
agent work from that precise visual context. Visual Intent Layer is a local MCP
server and Review Surface for saved HTML documents and local web apps.

## About

hello world! this project is a testbed for me to experience new/random/trending stuff!
fyi on what i was testing:

- [pstack's verification skills](https://github.com/cursor/plugins/tree/main/pstack)
- [matt's skills](https://github.com/mattpocock/skills/tree/main)
- ds v4.1 flash via openrouter in pi
- ...

## Key features

- **Direct pointing.** Point, drag, or box visible targets instead of describing their location in prose.
- **Annotations with context.** Group targets into one Annotation and attach reference images when useful.
- **Delivery state you can read.** Keep unsent and delivered Annotations together with their revision and resolution state.
- **Human judgement.** Review the result in a browser and decide each Annotation by hand.
- **Local by default.** Keep review data on the local machine.

Mobile builds, native windows, design files, and PDFs are outside the supported surface.

## Requirements

- Node.js 20 or newer
- A browser on the machine running the server
- An MCP-capable agent, if you want an agent to use the Review Surface

No hosted account or Rust toolchain is required.

## Quickstart

Register the local stdio server with your agent, then restart the agent:

```json
{
  "mcpServers": {
    "visual-intent-layer": {
      "command": "npx",
      "args": ["-y", "--package", "visual-intent-layer@latest", "visual-intent-mcp"]
    }
  }
}
```

The server must run on the machine where you look at the screen. It launches a
browser there and binds a loopback port. A server in a container, on a remote
host, or inside a cloud agent cannot display that machine's Review Surface.

Registry-aware clients can also find the server as
`io.github.willa-code/visual-intent-layer` in the official MCP Registry, which
lists where to get it rather than hosting it.

<details>
<summary>Claude Code</summary>

```sh
claude mcp add visual-intent-layer -- npx -y --package visual-intent-layer@latest visual-intent-mcp
```
</details>

<details>
<summary>Codex</summary>

```sh
codex mcp add visual-intent-layer -- npx -y --package visual-intent-layer@latest visual-intent-mcp
```
</details>

<details>
<summary>opencode</summary>

Run `opencode mcp add visual-intent-layer`, then provide `npx` and the package
arguments when prompted:

```text
-y --package visual-intent-layer@latest visual-intent-mcp
```
</details>

<details>
<summary>pi</summary>

`pi` does not ship an MCP client. With `pi-mcp-adapter` installed, add this to
the project's `.mcp.json` (merge it into an existing `mcpServers` object):

```json
{
  "mcpServers": {
    "visual-intent-layer": {
      "command": "npx",
      "args": ["-y", "--package", "visual-intent-layer@latest", "visual-intent-mcp"]
    }
  }
}
```

The same entry can be placed in `.pi/mcp.json` for a project-only Pi override,
or `~/.config/mcp/mcp.json` for all projects. The adapter's `/mcp setup` panel
can also create the entry.
</details>

<details>
<summary>Other MCP clients</summary>

Use the JSON configuration above, or launch a local stdio server with command
`npx` and arguments `-y --package visual-intent-layer@latest
visual-intent-mcp`.
</details>

## Start a review without an agent

The package also provides a local CLI:

```sh
npx -y --package visual-intent-layer@latest visual-intent open --html ./checkout.html
npx -y --package visual-intent-layer@latest visual-intent open --app http://localhost:5173
```

Each command opens the default browser and prints the review URL. Add
`--no-open` for headless or scripted use. To run only the local service:

```sh
npx -y --package visual-intent-layer@latest visual-intent serve --port 3742
```

The `visual-intent` command is also available after
`npm install -g visual-intent-layer`.

## Data and privacy

The server writes review data to `~/.visual-intent-layer/data` by default. It
does not write agent configuration. Uninstalling the package does not delete
reviews; remove that data directory only when you want to remove them.

Set `VISUAL_INTENT_DATA_DIR` to choose another data directory. Set
`VISUAL_INTENT_NO_OPEN=1` to suppress automatic browser opening.

## Update and uninstall

`@latest` is resolved when `npx` fetches the package, so there is usually
nothing to update by hand. `pi-mcp-adapter` caches the resolved command for 24
hours; delete `~/.pi/agent/mcp-npx-cache.json` to force a fresh fetch. Replace
`@latest` with an exact version in the entry to hold a version still, and update
a global install with `npm install -g visual-intent-layer@latest`.

To uninstall, remove the entry with the mechanism you added it with — `claude
mcp remove visual-intent-layer`, `codex mcp remove visual-intent-layer`, or by
editing your client's configuration. [`docs/guide.md`](docs/guide.md) names the
file for each client. Uninstalling deletes none of your reviews: they stay in
the data directory until you remove it.

## Documentation

- [`docs/guide.md`](docs/guide.md) — product manual, Review Surface, Annotation model, MCP tools, data, schema, development, and layout.
- [`design.md`](https://github.com/willa-code/visual-intent-layer/blob/main/design.md) — normative Review Surface design contract.
- [`docs/design-references.md`](https://github.com/willa-code/visual-intent-layer/blob/main/docs/design-references.md) — component references and verification notes.
- [`docs/reference-foundations.md`](https://github.com/willa-code/visual-intent-layer/blob/main/docs/reference-foundations.md) — comparison of candidate reference foundations.
- [`SECURITY.md`](https://github.com/willa-code/visual-intent-layer/blob/main/SECURITY.md) — threat model, supported versions, and disclosure process.
- [`docs/adr/`](https://github.com/willa-code/visual-intent-layer/tree/main/docs/adr) — architectural decisions.
- [`docs/pi-validation.md`](https://github.com/willa-code/visual-intent-layer/blob/main/docs/pi-validation.md) — live Pi validation checklist.

## License

Apache-2.0.