Ghostly is a local-first E2E testing engine that translates natural-language goals into fully automated Playwright browser flows. Instead of writing and maintaining fragile CSS selectors or step-by-step scripts by hand, you describe what you want to verify — “log in and confirm the dashboard loads” — and Ghostly’s AI pipeline plans the steps, executes them in a real Chromium browser, self-heals broken selectors when the UI drifts, and streams the result to a live dashboard. Everything runs on your machine: credentials, test data, and run artifacts never leave your developer environment.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Meza-dev/Ghostly/llms.txt
Use this file to discover all available pages before exploring further.
Why Ghostly?
Modern front-end applications change fast. Selector-based test suites break every sprint, and the maintenance cost grows with the product. Ghostly attacks this problem from three directions:Natural-language goals
Describe what to test in plain English. Ghostly’s strategist LLM turns the goal into a Playwright step plan automatically.
Self-healing selectors
When a selector fails, the healer agent reads the live accessibility tree and proposes a repair — no manual intervention required.
BYO-LLM
Bring your own provider. Ghostly works with any OpenAI-compatible HTTP endpoint or a local Cursor CLI — you own the inference.
Core capabilities
- Playwright execution engine — steps run in a real Chromium browser managed by Playwright, with optional video recording, screenshots, and accessibility snapshots after each action.
- Assisted pipeline — a three-agent loop: the strategist plans step horizons from the goal, the observer captures the a11y tree after each action, and the healer repairs any broken selectors before retrying.
- Live SSE dashboard — a React SPA served by the local API at
http://localhost:4000streams run events in real time, so you can watch each step unfold as it executes. - AssistMemory — successful runs are stored in SQLite and replayed on future executions of the same goal, making repeated runs faster and more stable.
- MCP server — exposes Ghostly’s tools (
ghostly_run_flow,submit_plan,get_project_map, and more) to MCP-compatible IDEs such as Cursor, letting you trigger tests directly from your editor.
Architecture at a glance
Ghostly is a monorepo of cooperating services, all orchestrated by a single CLI command:ghostly up— migrates the local SQLite database, generates the Prisma client, then spawns the Hono API server and serves the React dashboard as static files on the same port.- API (
apps/api) — receives test goals, calls the LLM strategist, persists runs and events, and streams SSE progress back to the browser. - Runner (
@ghostly-io/runner) — the Playwright execution engine. Supports two modes:runFlow(direct step list) andrunAssistedFlow(AI-driven, self-healing). - MCP Server (
packages/mcp-server) — bridges the IDE to Ghostly’s REST API, so Cursor users can submit goals without leaving their editor.
System requirements
| Requirement | Details |
|---|---|
| Node.js | v20 or later |
| Chromium | Managed automatically by Playwright via ghostly install |
| MCP-compatible IDE | Optional — Cursor recommended for full IDE integration |
| Operating system | macOS, Linux, or Windows (PowerShell / WSL) |
Ghostly is designed for local-first use. All API keys, LLM credentials, and test artifacts are stored on your machine in
~/.ghostly/ and a local SQLite database. Nothing is sent to an external Ghostly cloud service.Explore Ghostly
Quickstart
Install the CLI, generate credentials, and run your first test in under 5 minutes.
Architecture
Deep-dive into the monorepo layout, each component’s role, and the assisted-run lifecycle.
CLI Reference
Full reference for
ghostly keygen, install, config, up, and update.Assisted Mode
How the strategist–observer–healer pipeline turns a plain-English goal into passing Playwright steps.