ghostlight

<p align="center">
  <img src="extension/icons/ghostlight-mascot.png" alt="Ghostlight mascot: a small sky-blue pixel-art ghost holding a glowing lantern" width="100" height="100">
</p>

<h1 align="center">Ghostlight</h1>

<p align="center"><strong>Your real browser, for any MCP agent -- visible, local, and yours.</strong></p>

<p align="center">
  <a href="https://github.com/sylin-org/ghostlight/actions/workflows/ci.yml"><img src="https://github.com/sylin-org/ghostlight/actions/workflows/ci.yml/badge.svg?branch=dev" alt="CI"></a>
  <a href="https://www.npmjs.com/package/ghostlight"><img src="https://img.shields.io/npm/v/ghostlight?color=38BDF8&label=npm" alt="npm"></a>
  <a href="https://github.com/sylin-org/ghostlight/releases/latest"><img src="https://img.shields.io/github/v/release/sylin-org/ghostlight?color=38BDF8&label=release" alt="release"></a>
  <a href="https://registry.modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP_registry-org.sylin%2Fghostlight-38BDF8" alt="MCP registry"></a>
  <a href="https://github.com/sylin-org/homebrew-tap"><img src="https://img.shields.io/badge/Homebrew-sylin--org%2Ftap-38BDF8" alt="Homebrew tap"></a>
  <a href="https://glama.ai/mcp/servers/sylin-org/ghostlight">
    <img src="https://glama.ai/mcp/servers/sylin-org/ghostlight/badges/score.svg" alt="Ghostlight score on Glama">
  </a>
</p>

<p align="center"><img src="docs/assets/demo.gif" alt="Ghostlight reading and completing a launch brief in a real browser with visible page, field, and click feedback" width="838" height="766"></p>
<p align="center"><sub>Ghostlight reading, filling, and completing a brief in the user's visible browser.</sub></p>

<p align="center"><a href="#try-it"><strong>Install and try it</strong></a> | <a href="docs/guides/installation.md">Every install path</a> | <a href="https://sylin.org/ghostlight/decision-aid/">Choose a browser-control approach</a> | <a href="docs/COMPARISON.md">Compare alternatives</a></p>

Ghostlight lets an AI agent use the Chromium profile where you are already signed in, inside a
dedicated tab group that stays separate from your ordinary tabs. Actions happen in front of you. It
works wide open for personal use or under inspectable policy when stronger boundaries are useful.
Everything runs locally, and nothing phones home.

**No account and no subscription trap.** The local browser automation core is Apache-2.0 OR MIT
and runs without a Ghostlight login, activation server, telemetry, or subscription. Organizational
governance is a separately licensed source-available layer. Personal use, evaluation, development,
small teams, and unrestricted all-open operation remain free under the exact terms linked in
[License](#license).

Responsibility is part of the experience, not a brake on it. A good agent tool should be easy to
start, obvious while it acts, clear when it stops, and honest about what it can and cannot control.

## Is this your problem?

Ghostlight is worth trying when:

- your agent needs a site where you are already signed in, not a fresh browser profile;
- you want the same browser tools from Codex, Claude, Cursor, VS Code, Windsurf, Zed, OpenCode,
  Crush, or another MCP client;
- you want to watch the work, take the wheel, and understand failures without decoding logs; or
- you need policy and evidence that a developer and a security reviewer can both inspect.

It is probably not the right tool for a headless scraping farm, stealth automation, an isolated
cloud browser, or a Claude-only setup already served by Anthropic's first-party integration. The
interactive [browser-control decision aid](https://sylin.org/ghostlight/decision-aid/) helps you
choose by operating model. The [comparison guide](docs/COMPARISON.md) provides the detailed
capability evidence behind those choices.

## What makes it feel different

- **Your session, not a clean-room.** Real cookies and real SSO, used only in Ghostlight-managed
  tabs. Nothing gets relocated to a cloud browser or a throwaway profile just to gain a technical
  property; the whole point is your authenticated context without opening your ordinary tabs.
- **The agent gets a tool surface shaped for models.** The trained schemas stay byte-stable;
  additive tools provide forms, files, multi-step composition, recording, and inspection. Results
  are compact, errors say how to recover, and a capable agent can begin without a Ghostlight lesson.
- **The person watching can follow along.** Every move is visible: sky-blue click ripples, a comet trail on
  drags, a shimmer as it types, captions that narrate each step. It runs in its own tab group, kept
  visually separate from your own tabs, and you can grab the wheel or hit the kill switch at any
  moment.
- **Responsibility scales with the job.** Personal use needs no policy. When boundaries matter,
  Ghostlight adds capability grants, sacred never-touch domains, dry-run preflight, and one
  structured record per call. The unrestricted engine remains a first-class product.
- **The software stays yours.** The Rust service and its thin relay have no runtime framework to
  maintain. The engine is open source, the governance code is readable, license state never changes
  behavior, and an installed copy keeps working offline.

## Try it

Needs a Chromium browser (116+), an MCP client, and Node for the `npx` install path. The running
service is native Rust; there is no Node service to keep alive and nothing to compile.

```text
[1 Install service] -> [2 Add extension] -> [3 Restart MCP client] -> [4 Ask a first task]
      automatic           visible step             once                useful proof
```

1. **Install the local service and register detected MCP clients:**

   ```sh
   npx -y ghostlight install
   ```

   The installer is idempotent and opens the extension walkthrough on the first run. It recognizes
   Claude Code, Claude Desktop, Cursor, VS Code, Codex, Windsurf, Zed, OpenCode, and Crush. Use
   `--client <id>` to target one client, or `--dry-run` to inspect every planned change first.

2. **Add the extension.** Install
   [Ghostlight in Browser](https://chromewebstore.google.com/detail/ghostlight-in-browser/lejccfmoeogmhemakeknjjdhkfkgncdl)
   from the Chrome Web Store.

3. **Restart your MCP clients.** The browser tools appear. Try:

   > In my current browser, summarize the active page and tell me which tab you used. Do not click
   > or change anything.

If anything looks off, `npx ghostlight doctor` tells you exactly what. Prebuilt archives, building
from source, and every other path live in the [installation guide](docs/guides/installation.md).

For an unsupported client, add `{ "command": "npx", "args": ["-y", "ghostlight"] }` as a stdio
MCP server, then run the installer for the browser side. For VS Code, use its native installer:

[![Add to VS Code](https://img.shields.io/badge/VS_Code-Add_MCP_server-38BDF8?style=flat-square)](vscode:mcp/install?%7B%22name%22%3A%22ghostlight%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22ghostlight%22%5D%7D)

**Current platform state.** Windows and Linux are verified end to end against live browsers. macOS
builds and passes the full test suite in CI; its live-browser verification is still owed.

**Extension state.** The Chrome Web Store serves Chrome adapter v0.6.0. Chrome adapter v0.6.0
covers Ghostlight service versions v0.6.0-v0.7.3. Chrome adapter v0.7.1 is pending review. Chrome
adapter v0.7.1 covers Ghostlight service versions v0.7.1-v0.7.3. Install the extension from the
public listing. See the full [adapter compatibility map](compatibility.json).

**Other ways to get it.** Homebrew: `brew install sylin-org/tap/ghostlight`. On the
[MCP registry](https://registry.modelcontextprotocol.io) as `org.sylin/ghostlight`. Every release
also ships prebuilt binaries and checksums on the
[Releases page](https://github.com/sylin-org/ghostlight/releases/latest).

<details>
<summary><strong>Build from source and test locally</strong></summary>

1. **Build the binary.** Clone this repository and run `cargo build --release` with a stable Rust
   toolchain. The build produces two executables:
   `ghostlight` (the CLI) and `ghostlight-relay`, the thin pass-through that your MCP client
   and Chrome launch.
2. **Load the development extension for immediate testing.** Open `chrome://extensions`, enable
   Developer mode, choose `Load unpacked`, and select this repository's `extension/` directory.
   The committed manifest key pins the development extension ID, and the installer already allows
   it, so there is nothing to copy.
3. **Register.** `./target/release/ghostlight install`. Useful flags: `--dry-run` (print the
   plan, write nothing), `--browser <id>` / `--client <id>` (limit scope; repeatable),
   `--all-browsers` / `--all-clients`, `--no-open`, `--debug` (observability on), and `--system`
   (machine-wide).
   The installer is an idempotent value-level merge; it never clobbers your config and never
   duplicates entries.
4. **Restart the client, reload the extension, run `ghostlight doctor`.** A healthy result
   reports registration, a live endpoint, and a connected extension; anything off gets a
   specific, actionable finding.

</details>

## What the agent can do

A typical first request:

> Open a new browser tab, go to example.com, and tell me what the page says.

The tool surface preserves the schemas Claude was trained on, byte for byte, then adds more on
top, for 25 tools in five groups. (Everything behind those schemas is an original, clean-room
Rust implementation.)

- **See and act.** Navigate, click, type, scroll, hover, drag; screenshots with exact coordinate
  mapping and an on-page cursor; semantic one-call actions with bounded outcome receipts.
- **Forms and files.** Fill forms by element ref or semantically by label (shadow DOM included);
  upload file bytes or captured screenshots straight into page inputs and drop targets.
- **Compose.** Multi-step scripts with inter-step dat