ghostlight

Ghostlight provides compatible AI agents with a visible workspace in the Chromium browser you already use, local-first, with optional policy and audit.

Purpose

When an agent needs to operate a page you are already logged into, the common approach is to launch a second blank browser that knows nothing about your sessions, and the model must learn Chrome internals to get the work done. Ghostlight instead assigns the agent a tab group in the Chromium you already have open, and the work happens in front of you: you can watch, pause, take over, or end the session. The model expresses intent, and Ghostlight handles the browser part.

Have the agent read pages, fill forms, handle files, follow pop-ups, or investigate failed web workflows. Ghostlight carries tasks across tabs and browser changes, while keeping browser work and its control on your machine.

Main capabilities

• 24 directory tools: 23 browser tools covering tabs, navigation, reading pages, screenshots, semantic click and hover, form input, file upload, scripts, waiting, short flows, dialogs, diagnostics, and workspace switching; plus 1 policy tool for explaining the permissions currently in effect.
• One real answer per call: states what happened, what changed in the browser, what is ready, and whether it is safe to run again. Ghostlight writes that answer itself, not the page; it adds at most two recovery steps on its own. When the effect is uncertain it says so clearly rather than guessing, and never proposes a replay that could resubmit a form.
• Desktop workbench: lives in the tray and shows the work in real time.
• Runs locally: Ghostlight runs as you, accesses the browser via local IPC, and keeps a payload-free local record. No account, no telemetry, no activation service, no update ping, no hosted control plane, no second hidden browser. The only network traffic is the browsing you requested.

How to use

Requirements

Requires Chrome, Edge, Brave, or Chromium 125+, an MCP client, and Node.js for the installer. The service that runs afterward is native Rust.

Installation

Install Ghostlight and register the MCP clients it finds:

npx -y ghostlight install

Add Ghostlight in Browser from the Chrome Web Store.

If the MCP client does not support hot-reloading tools, restart it.

First verification

Give it a small read-only task:

Open in a new Ghostlight tab https://example.com/，总结页面，并告诉我你使用了哪个标签页。不要点击、输入、提交或更改页面。

A sky-blue Ghostlight group should appear in the browser. The agent opens the page, reads it, and says the exact tab it used. This one prompt proves the whole connection, without an authorization click or a write. Next time it will reuse that group and the most recent tab it already has on that site, so repeated work no longer clutters your tab bar.

If a step needs attention, run:

doctor

It checks the client entry point, local service, browser connection, and extension, then points out the next step. The installation guide covers target clients, source builds, updates, uninstallation, and symptom-oriented recovery.

From a single page to a complete workflow

Ghostlight performs best when browser work has a trail to follow:

• Continue from where you are already logged in: Open the app in the Chromium profile you choose and use the existing session. Credentials stay in the browser.
• Complete interactions: Navigate, fill out forms, upload files, handle dialogs, wait for page states, and carry results from one step to the next.
• Follow the browser: When a site opens a supported child tab, or a known workspace changes beneath the task, continue working.
• See why it failed: Bring page state, console messages, and network requests together so the next debugging step is based on evidence rather than guesswork.

The same browser capabilities are available from Codex, Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, OpenCode, Crush, or other compatible stdio MCP clients. Agents get structured page reads, precise element references, bounded action receipts, and concrete recovery guidance. They can ask the policy tool at any time to explain the permissions currently in effect.

The browser remains a shared space

Ghostlight works in a dedicated sky-blue tab group within the browser window you choose. Page scans, clicks, typing, drags, and longer phases share a visual language, so actions on screen are explained.

You can pause the workspace, take over for fine-grained steps, or stop it. Move tabs where you want them; Ghostlight follows the workspace instead of snapping it back. Ordinary tabs remain outside the agent-owned set.

Closing a tab requires two separate consents: the orchestrator's permission, and the browser's own tab retention setting (on by default). This keeps the evidence of what happened in front of you. Closing a tab yourself always works.

Policy and audit (optional)

Personal use is fully available without a policy manifest. Start with the full browser engine and get useful work done. When a workflow needs stronger boundaries, grant read, action, write, and execute capabilities by MCP identity and domain. Add sacred domains, dry-run preflight, and structured auditing while the browser experience remains unchanged. The governance guide shows the operating model, and the trust center provides security, privacy, continuity, and partdepartment and procurement evidence.

Applicable scenarios

• Operate applications in a logged-in Chromium profile, using the existing session.
• Complete browser tasks requiring multi-step interaction: navigation, form filling, uploads, handling dialogs, waiting for states.
• Follow supported sub-tabs or workspace changes opened by the site.
• Debug failed web workflows, gathering page state, console, and network requests.
• Use the same browser capabilities from a variety of compatible MCP clients (Codex, Claude Code, Cursor, VS Code, etc.).

Limitations

• Without policy configuration: HTTP(S) browsing is allowed, including localhost, loopback, and link-local targets. Host restrictions are part of policy. Non-HTTP schemes and expired handles remain restricted. Optional local and hosted policy layers can only revoke capabilities.
• Credential input: Requires your explicit instruction. Filling and input accept the agent's per-request confirmation; without confirmation, the call returns guidance without pausing the session. This confirmation cannot override policy or your pause/stop controls. Repeated policy denials also do not affect subsequent allowed work.
• Browser messages and animations: Remain passive, have no buttons, and do not interfere with your input; interactive runtime controls belong to the workbench.
• Audit records: Contain identifiers, decisions, and content-minimized metrics: which tool ran, whether permission allowed it, how long it took, what was done—3 fields, 1,240 words, 1280x720. Sites where actions land are named, because this answers where your agent went, and it is already in your own tab bar. Paths, queries, fragments, page text, field values, screenshots, selectors, and dialog text never enter it.
• Platform status: Windows and Linux are supported 1.0 platforms, verified on a live browser on the development host; the clean installed-product evidence channel continues after release. macOS has no 1.0 artifact yet.
• Extension status: The Chrome Web Store listing provides adapter v1.3.12, compatible with service 1.3.14 under adapter protocol 3. Service updates use a fixed install path and the existing injector; no extension update or reload is needed.
• Build requirements: Rust 1.82 or newer, plus Chromium 125 or newer for browser verification.

Licensing and continuity

Ghostlight is completely free and open source: everything in this repository, including governancemodules, is Apache-2.0 OR MIT. LICENSING.md explains its coverage. The previous open-core split and its paid tiers have been withdrawn by ADR-0140.

License status never enters the runtime—no license check can reach it. Installed copies continue to work under their own terms, with no check-in and no expiration. The continuity commitment carries its durable version.

Questions and contributions

For reproducible defects, please use GitHub Issues; for questions and ideas, please use GitHub Discussions; for security, licensing, or anything that should not be public, please email hello@sylin.org.