Sherlock

Apple Developer documentation, instantly searchable in Claude Code.

Built by Hotfix and used to ship our iOS app.

Demo

Sherlock answering Apple framework questions in Claude Code using only the local doc index.

SwiftUI lifecycle: .task vs .onAppear vs .onChange

UIKit: viewIsAppearing vs viewWillAppear vs viewDidAppear

Background tasks: BGAppRefreshTask vs BGProcessingTask

Why

Claude hallucinates Apple APIs constantly. Invented method names, wrong parameter labels, deprecated symbols presented as current. The fix is grounding: give Claude a local, searchable copy of developer.apple.com and a skill that tells it when to actually look things up.

Sherlock indexes ~70,000 symbols across Swift, SwiftUI, UIKit, Foundation, Combine, Core Data, SwiftData, Core ML, MapKit, AVFoundation, and more into a SQLite FTS5 database, then serves them to Claude as MCP tools. Named after Apple's original macOS search app (and the dev folklore around it).

Install

/plugin marketplace add hotfix-jobs/sherlock
/plugin install sherlock

Prerequisites

The MCP server runs in Python, so users need:

• Python 3.9 or newer on the system PATH (python3 --version)
• The mcp and zstandard Python packages (Claude Code installs them automatically the first time the plugin runs)

If python3 is not available, the plugin will fail to start. On macOS, install with brew install python or use the Python from Xcode Command Line Tools.

What you get

Five MCP tools your agent can call directly

Three skills that teach Claude when to reach for those tools

Works great with Superpowers

Sherlock pairs naturally with the Superpowers Claude Code plugin. Use Superpowers' brainstorming, planning, and TDD skills to figure out what to build; Sherlock grounds the how in Apple's actual API surface. The skills in this plugin defer to Superpowers when both are installed, so you get composition rather than overlap.

How it works

┌──────────────────────┐         ┌────────────────────┐
│  GitHub Actions (CI) │         │  Your machine      │
│                      │         │                    │
│  weekly cron:        │ Release │  /plugin install   │
│  - crawl Apple docs  │ ──────▶ │  sherlock          │
│  - build markdown    │   .zst  │                    │
│  - build FTS5 index  │         │  first tool call:  │
│  - publish artifacts │         │  - DL index (~50MB)│
└──────────────────────┘         │  - DL frameworks   │
                                 │    on demand       │
                                 └────────────────────┘

• Index DB (~50 MB) downloads once on first tool call → ~/.claude/data/sherlock/index.db
• Per-framework markdown bundles (~10-30 MB each) fetched the first time you read a page in that framework
• All data is cached locally; subsequent reads are instant
• Corpus rebuilt weekly from developer.apple.com

Override paths with SHERLOCK_DATA_DIR and SHERLOCK_RELEASE_BASE env vars.

Building the corpus

End users never build the corpus. The whole architecture exists so they don't have to: GitHub Actions runs the crawl once a week and publishes ready-to-use artifacts to Releases. The plugin downloads those.

Triggering a fresh build (org admins)

gh workflow run build-corpus.yml

Or trigger a partial build for one framework via the workflow's manual-dispatch input.

Local development of the plugin

You do not need to re-crawl Apple. Point SHERLOCK_RELEASE_BASE at the live Releases URL (or any HTTP server hosting a prior index.db.zst and sherlock-*.tar.zst) and run the MCP server.

Local development of the build pipeline itself

One streaming script does discovery, fetch, markdown conversion, and SQLite FTS5 indexing in a single pass. Test it against one framework:

pip install -r scripts/requirements.txt
python scripts/build_corpus.py --frameworks swiftui --out-dir dist

That writes dist/index.db, dist/markdown/swiftui/..., and dist/manifest.json. Tune --concurrency (default 16) up or down based on what Apple's servers tolerate; the script backs off automatically on 429s.

What the script does

1. Auto-discovers framework slugs from developer.apple.com/documentation/ (or accepts an explicit --frameworks list)
2. BFS-crawls each framework's JSON API with HTTP/2 connection pooling and a configurable concurrency cap
3. Converts each page's JSON to markdown in memory
4. Writes the markdown file and inserts an FTS5 row in the same loop
5. Never persists raw JSON to disk

sherlock/
├── .claude-plugin/
│   └── marketplace.json       # marketplace manifest (lists sherlock as a plugin)
│
├── plugin/                    # what users install
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── skills/
│   │   ├── docs/SKILL.md
│   │   ├── api-availability/SKILL.md
│   │   └── signature-verification/SKILL.md
│   └── mcp/                   # MCP server (Python)
│       ├── server.py
│       ├── search.py          # SQLite FTS5
│       ├── fetch.py           # lazy install + cache
│       └── requirements.txt
│
├── scripts/                   # CI build pipeline (users never run these)
│   ├── build_corpus.py        # streaming async crawler + indexer
│   └── requirements.txt
│
└── .github/workflows/
    └── build-corpus.yml       # weekly Mon 06:00 UTC + manual dispatch

Contributing

PRs welcome. Most useful contributions:

• Adding new framework slugs to the fallback list in scripts/build_corpus.py
• Improving the JSON-to-markdown converter for cleaner output
• New MCP tools (e.g., symbol-graph traversal, deprecation lookups)
• Reducing the index size (better summary extraction, smarter FTS tokenization)

License

MIT (see LICENSE). Documentation content © Apple Inc., redistributed for offline AI/developer reference. Not affiliated with Apple.

Credits

Built by Hotfix.