Limelight gives Codex and local agents a searchable window into your Mac's context: files, photos, mail, messages, notes, calendar, contacts, reminders, and Safari history.

It runs locally on your Mac and exposes a small loopback HTTP API so any agent or model can utilise it.

• Install
• Use With Codex
• Use With Agents
• What It Can Search
• Developer Quick Start
• Documentation
• Project Layout

Download the latest pre-built .dmg from GitHub Releases, open it, and drag Limelight into your Applications folder.

After installing:

1. Launch Limelight.
2. Grant the macOS permissions it asks for.
3. Grant Full Disk Access to Limelight in System Settings for protected sources such as Mail, Messages, Notes, Safari, and some Calendar/Reminders stores.

Once running, Limelight listens on 127.0.0.1:8765 by default.

See Installation for local development installs, signing, and LaunchAgent setup.

Install the Limelight Codex Plugin to use Limelight directly from Codex.

Agents can query Limelight through its local HTTP API. A basic search looks like this:

curl -s http://127.0.0.1:8765/v1/search \
  -H 'X-Origin: Example Agent' \
  -H 'Content-Type: application/json' \
  -d '{"query":"passport","sources":["photos"],"types":["image"],"limit":5}'

For deeper integrations, see API Reference, the Python client, and the TypeScript client.

Limelight can search:

• files through native Spotlight metadata
• Photos library search/person indexes
• Contacts, Calendar, and Reminders through macOS frameworks and local fallbacks
• Notes, Mail, and Safari through local protected stores when Full Disk Access is granted

It does not persist a search cache and does not expose full document text by default. See Providers for provider behavior, permissions, and caveats.

Requirements:

• macOS 14 or newer
• Swift 6 toolchain
• jq for probe scripts

Run the service directly:

swift run spotlight-index --host 127.0.0.1 --port 8765

Check that it is listening:

curl http://127.0.0.1:8765/health

Run tests:

swift test

Build a signed release DMG with scripts/package-release.sh.

Use the scripts in scripts/ for validation probes, packaging, and local app builds.

• Installation: DMG install, local app install, signing, and LaunchAgent.
• Providers: searchable sources, permissions, readiness, and limitations.
• API Reference: endpoints, request examples, toolbox endpoints, and origin headers.
• Capability Matrix: generated local runtime provider capability snapshot.
• Python Client: dependency-free Python client for the local HTTP API.
• TypeScript Client: typed fetch client for Node 18+ and browsers.

Sources/SpotlightIndexCore/   Core search providers, HTTP API, models, and permission helpers
Sources/spotlight-index/      CLI entry point and menu bar app shell
Tests/                        Swift tests for query building, normalization, providers, and integration behavior
scripts/                      Local install, signing, probes, and validation utilities
clients/python/               Small Python SDK for the local HTTP API
clients/typescript/           TypeScript SDK for Node 18+ and browsers
docs/                         Installation, API, provider, development, and capability docs