<div align="center">
  <h1>
    <img src="packages/website/public/brand/kit/svg/rectangle-light.svg" alt="Agent Lighthouse" width="560">
  </h1>
  <p><strong>Lighthouse, but for AI agents.</strong></p>
  <p>Audit whether ChatGPT, Claude, Perplexity, MCP clients, AI crawlers, and agentic browsers can discover, parse, cite, and act on your website.</p>
  <p>
    <a href="https://www.npmjs.com/package/@forkpoint/agent-lighthouse"><img alt="npm version" src="https://img.shields.io/npm/v/@forkpoint/agent-lighthouse.svg?color=4f46e5"></a>
    <a href="https://www.npmjs.com/package/@forkpoint/agent-lighthouse"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@forkpoint/agent-lighthouse.svg"></a>
    <a href="https://github.com/ForkPoint/agent-lighthouse/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/ForkPoint/agent-lighthouse/actions/workflows/ci.yml/badge.svg"></a>
    <a href="https://forkpoint.github.io/agent-lighthouse/"><img alt="Docs" src="https://img.shields.io/badge/docs-GitHub%20Pages-4f46e5"></a>
    <a href="./LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
  </p>
  <p>
    <a href="https://forkpoint.github.io/agent-lighthouse/">Documentation</a>
    ·
    <a href="https://www.npmjs.com/package/@forkpoint/agent-lighthouse">npm</a>
    ·
    <a href="https://github.com/ForkPoint/agent-lighthouse/issues/new?template=site-score.yml">Share a site score</a>
    ·
    <a href="https://forkpoint.github.io/agent-lighthouse/branding/">Brand kit</a>
  </p>
</div>

Logo files, icons, and usage rules: [brand guide](packages/website/public/brand/BRAND.md).
Download the [complete brand kit](https://github.com/ForkPoint/agent-lighthouse/raw/refs/heads/main/packages/website/public/brand/agent-lighthouse-brand-kit.zip).

![Agent Lighthouse HTML report with the AI lighthouse logo, score summary, and website checks](docs/assets/report-screenshot.png)

Example report from a scan of zapier.com on 2 September 2026. Scores describe that scan, not the site's current state.

---

## ⚡ Quickstart

Requires Node.js 22.22.2+ (22.x), 24.15.0+ (24.x), or 26+.

Run a zero-install scan directly in your terminal. The `--view` flag opens the standalone HTML report for screenshots, stakeholder review, and pull-request artifacts.

```bash
# Instant audit (prints terminal report & generates HTML + JSON reports)
npx @forkpoint/agent-lighthouse https://yourstore.com

# Open the standalone HTML report in your browser
npx @forkpoint/agent-lighthouse https://yourstore.com --view

# Run in CI and fail if score is below threshold
npx @forkpoint/agent-lighthouse https://staging.yourstore.com --min-score 85
```

Agent Lighthouse checks 215 audits covering `llms.txt`, robots.txt crawler policy, Schema.org, OpenAPI discovery, WebMCP action surfaces, AEO/GEO content structure, agentic commerce, and operability.

---

## Agentic readiness skill

Use the [`agent-lighthouse` skill](plugins/agent-lighthouse/skills/agent-lighthouse/SKILL.md) with a coding agent to turn an Agent Lighthouse report into code review and verified fixes. It supports any website stack.

The skill reads the report, traces findings through source files and hosting settings, checks related routes, and verifies requested changes. It keeps local fixes separate from deployed scan results.

Install the plugin from this repository's marketplace. In Claude Code:

```sh
claude plugin marketplace add ForkPoint/agent-lighthouse
claude plugin install agent-lighthouse@agent-lighthouse
```

In Codex:

```sh
codex plugin marketplace add ForkPoint/agent-lighthouse
codex plugin add agent-lighthouse@agent-lighthouse
```

To install from a local checkout, pass `/absolute/path/to/agent-lighthouse` to `marketplace add` instead, then run the same install command. Start a new chat after installation.

Example: “Use the `agent-lighthouse` skill to assess this site's Agent Lighthouse report and source code. Fix confirmed issues and verify the changes.”

Read the [installation and workflow guide](packages/website/src/content/readiness-skill.md). The marketplace packages the skill and its references. The CLI and MCP npm packages remain separate.

---

## 🎯 What Agent Lighthouse Checks

Agent Lighthouse evaluates websites across **8 agent-journey categories** grouped into **3 readiness pillars**:

```
├── 1. Agentic Readiness
│   ├── Access & Crawl Control (robots.txt rules for GPTBot, ClaudeBot, PerplexityBot, blocks, status codes)
│   ├── Machine Discovery (llms.txt, llms-full.txt, sitemaps, feeds, .well-known surfaces)
│   ├── Agent Interfaces (WebMCP manifests, OpenAPI specs, agents.json, search actions)
│   └── Agentic Commerce (product offers, availability, checkout and payment surfaces)
│
├── 2. AI Search Optimization
│   ├── Content Extraction (clean main content, semantic structure, render and response cost)
│   ├── Structured Data (Schema.org Product, Offer, SKU, GTIN, Organization, JSON-LD validity)
│   └── Answer Readiness (direct answerability, step lists, tables, unique data, citations)
│
└── 3. Technical Foundation
    └── Agent Operability & Safety (HTTPS, security.txt, tdmrep, stability, broken agent endpoints)
```

---

## 📦 Packages & Architecture

This repository is organized as a lightweight pnpm monorepo published under the **`@forkpoint`** scope:

| Package               | npm Package                                                                                              | Description                                                     |
| :-------------------- | :------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- |
| **`packages/cli`**    | [`@forkpoint/agent-lighthouse`](https://www.npmjs.com/package/@forkpoint/agent-lighthouse)               | Main CLI binary (`npx @forkpoint/agent-lighthouse <url>`).      |
| **`packages/core`**   | [`@forkpoint/agent-lighthouse-core`](https://www.npmjs.com/package/@forkpoint/agent-lighthouse-core)     | Core gatherer-audit engine, scoring algorithms, and types.      |
| **`packages/report`** | [`@forkpoint/agent-lighthouse-report`](https://www.npmjs.com/package/@forkpoint/agent-lighthouse-report) | Standalone HTML, Markdown, and unified report view-model.       |
| **`packages/mcp`**    | [`@forkpoint/agent-lighthouse-mcp`](https://www.npmjs.com/package/@forkpoint/agent-lighthouse-mcp)       | Model Context Protocol (MCP) server for Claude / Cursor / IDEs. |

---

## 🛡️ GitHub Actions CI

Use Agent Lighthouse as a pull-request gate for agentic readiness regressions:

```yaml
name: Agent Lighthouse

on:
  pull_request:
    branches: [main]

jobs:
  agent-lighthouse:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: ForkPoint/agent-lighthouse@main
        with:
          url: https://staging.yourstore.com
          min-score: "85"
          github-token: ${{ secrets.GITHUB_TOKEN }}
```

The action generates terminal, HTML, JSON, and Markdown reports. Set `comment-on-pr: true` with `github-token` to post the Markdown summary on pull requests. See the [marketplace setup guide](docs/github-action.md) for release-ready examples.

---

## 💻 Programmatic Node.js / TypeScript SDK

```typescript
import { runScan } from "@forkpoint/agent-lighthouse-core";
import {
  buildReportView,
  generateHtmlReport,
} from "@forkpoint/agent-lighthouse-report";

const report = await runScan("https://example.com");
const view = buildReportView(report);

console.log(`Overall Score: ${view.overallScore}/100 (${view.scoreTier})`);

// Generate standalone HTML report
const html = generateHtmlReport(report);
```

---

## 🤖 Model Context Protocol (MCP) Server

Add Agent Lighthouse to your Claude Desktop or Cursor IDE to let AI coding agents audit live staging URLs:

```json
{
  "mcpServers": {
    "agent-lighthouse": {
      "command": "npx",
      "args": ["-y", "@forkpoint/agent-lighthouse-mcp"]
    }
  }
}
```

---

## 📣 Share Your Score

Generated reports are standalone files, so teams can attach them to pull requests, send them to clients, or publish before/after improvements.

```markdown
[![Agent Lighthouse](https://img.shields.io/badge/Agent%20Lighthouse-ready-4f46e5)](https://github.com/ForkPoint/agent-lighthouse)
```

If you run Agent Lighthouse on a public site, share the result through the [site score template](https://github.com/ForkPoint/agent-lighthouse/issues/new?template=site-score.yml). Good examples help other developers learn what agent-ready sites look like.

More material lives in:

- [Media kit](docs/media-kit.md)
- [Benchmark report](docs/benchmark.md)
- [Badge generator notes](docs/badge.md)
- [Terminal demo transcript](docs/assets/terminal-demo.txt)
- [Docs homepage screenshot](docs/assets/docs-home-screenshot.png)
- [Generated report screenshot](docs/assets/report-screenshot.png)
- [Badge generator screenshot](docs/assets/badge-generator-screenshot.png)
- [Report preview asset](docs/assets/report-preview.svg)
- [MCP setup screenshot asset](docs/assets/mcp-setup.svg)

---

## 🛠️ Development

```bash
# Clone the repository
git clone https://github.com/ForkPoint/agent-lighthouse.git
cd agent-lighthouse

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run unit tests
pnpm test
```

---

## 📄 License

Apache-2.0 © [ForkPoint](https://github.com/ForkPoint)