{
  "markdown": "![Hero](https://raw.githubusercontent.com/drewalth/claude-xcindex/main/assets/hero.png)\n\n# xcindex\n\nSemantic Swift/ObjC symbol lookups for Claude Code, powered by Xcode's\non-disk SourceKit index.\n\n[![build](https://github.com/drewalth/claude-xcindex/actions/workflows/build.yml/badge.svg)](https://github.com/drewalth/claude-xcindex/actions/workflows/build.yml)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-8A63D2)](https://claude.com/claude-code)\n\nA [Claude Code](https://claude.com/claude-code) plugin that lets Claude\nquery Xcode's existing symbol index instead of falling back to `grep`.\nReferences, overrides, conformances, and refactor impact analysis on\nSwift/ObjC code hit the same `indexstore-db` library SourceKit-LSP uses —\nUSR-authoritative, sub-millisecond warm, no re-indexing.\n\nIt reads the index Xcode already writes to DerivedData during build. No\ndaemon, no second copy of your source, no builds on your behalf. It warns\nwhen the index is stale rather than acting.\n\n## Requirements\n\n- macOS 14 (Sonoma) or later — `indexstore-db` requires macOS 14+.\n- Xcode 16 or later with command-line tools (`xcode-select --install`).\n- [Claude Code](https://claude.com/claude-code).\n- An Xcode project (`.xcodeproj` / `.xcworkspace`) built at least once.\n\n## Install\n\n```\nclaude plugin marketplace add anthropics/claude-plugins-community\nclaude plugin install claude-xcindex@claude-community\n```\n\nFirst run downloads the matching `xcindex` binary from the GitHub release\nand caches it under the plugin directory — no `npm install`, no manual\nbuild.\n\nThen, in a Swift project:\n\n```\n/xcindex-setup\n```\n\nThis confirms the binary is ready, locates your Xcode project, and — with\nyour confirmation — runs `xcodebuild` per scheme so the index is populated.\nSkip it if you build in Xcode yourself.\n\nVerify with `/plugin` and `/xcindex-status`. If anything looks off, run\n`./bin/xcindex-doctor`.\n\n<details>\n<summary>Install from a local clone</summary>\n\nUseful for pinning to a specific commit or hacking on the plugin:\n\n```sh\ngit clone https://github.com/drewalth/claude-xcindex.git\ncd claude-xcindex/service && swift build -c release\n```\n\nThen in Claude Code:\n\n```\n/plugin marketplace add /absolute/path/to/claude-xcindex\n/plugin install xcindex@xcindex-local\n```\n\nThe launcher detects the from-source build at\n`service/.build/release/xcindex` and symlinks it instead of downloading.\n</details>\n\n## Usage\n\nThe skills trigger automatically based on what you ask — no special syntax.\n\n- \"Where is `UserService` used?\"\n- \"What calls `fetchUser`?\"\n- \"What depends on `NetworkClient.swift`?\"\n- \"What will break if I change `AuthManager`?\"\n- \"Rename `fetchUser` to `loadUser` across the codebase.\"\n- \"What tests cover `ModelData.swift`?\"\n\n```\nYou: Find all callers of fetchUser.\nClaude: [mcp__xcindex__find_symbol → mcp__xcindex__find_references]\n        → 6 call sites across 4 files. Reads ±10 lines around each.\n        Returns a focused summary instead of 8 full-file reads.\n```\n\n`/xcindex-status` checks index freshness and reports which files have been\nedited since the last build.\n\n### Tips\n\n- **Build first.** The index only updates when you build. After a large\n  edit, rebuild in Xcode (or via `/xcindex-setup`) before asking for\n  references — stale results are annotated, not silently wrong.\n- **Lead with the symbol.** \"Where is `X` used\" beats \"find usages of the\n  thing that fetches users\" — name lookups disambiguate, USR lookups are\n  authoritative.\n- **Use it for renames.** Rename requests delegate to a subagent with\n  isolated context, so large renames don't bloat your main session.\n\n## MCP tools\n\nExposed under `mcp__xcindex__*`. Signatures and examples in\n[docs/tools-reference.md](docs/tools-reference.md).\n\n| Tool | Purpose |\n|---|---|\n| `find_symbol` | Name → candidate USRs with kind and defining file. |\n| `find_references` | Every occurrence with file, line, column, role. |\n| `find_definition` | The canonical definition site. |\n| `find_overrides` | All overriding implementations of a method. |\n| `find_conformances` | All types conforming to a protocol. |\n| `blast_radius` | Minimal set of files affected by editing a file. |\n| `status` | Index freshness, DerivedData path, last-build timestamp. |\n| `plan_rename` | Semantic rename plan tiered by confidence — see [docs/tools-reference.md](docs/tools-reference.md#tiers) for tier definitions, or [docs/coverage.md](docs/coverage.md) for what each pinned fixture surfaces. |\n\n## Skills & hooks\n\n- **`swift-refactor-plan`** — triggers on \"plan a rename / what would changing X involve?\". Produces a written refactor plan (sites, risks, recommended execution path) without making any edits.\n- **`swift-find-references`** — triggers on \"where is X used?\". Steers Claude off grep.\n- **`swift-blast-radius`** — triggers on \"what does this file affect?\". Skips shotgun reads.\n- **`swift-rename-symbol`** — triggers on committed rename requests. Delegates to a subagent so the main context doesn't balloon.\n- **`SessionStart` hook** — reports index freshness up front.\n- **`PostToolUse` hook** (Edit/Write/MultiEdit) — tracks Swift/ObjC edits so stale results are annotated. Never triggers a build.\n- **`PreToolUse` hook** (Grep) — when Claude is about to grep Swift/ObjC source (`*.swift`/`*.m`/`*.mm` glob, `type: swift`, or a Swift file path), injects a one-line reminder that the semantic xcindex tools and skills exist. Non-blocking — the Grep proceeds either way; free-text searches (TODOs, log messages) are unaffected.\n\n## Troubleshooting\n\nRun `./bin/xcindex-doctor` — it checks Xcode, `libIndexStore`, the cached\nbinary, and index freshness line-by-line with remediation hints. Full\ncatalogue in [docs/troubleshooting.md](docs/troubleshooting.md).\n\n## Development\n\n```sh\nmake build-debug    # debug build\nmake test           # run tests (expects external fixtures checked out)\nmake test_ci        # run tests as CI does — skips uncheckout fixtures\nmake test-hooks     # bash regression tests for the hooks\nmake help           # list all dev targets\n```\n\n`make test` runs the external-fixture coverage suites (TCA, swift-log), which\nneed those repos checked out under `tests/fixtures/`. On a fresh clone they\naren't present and the suites **fail by design** — a silent skip would register\nas a passing test with zero assertions. Either run `make test_ci`\n(sets `XCINDEX_ALLOW_FIXTURE_SKIP=1` and skips them, exactly as CI does), or\nfetch the fixtures first: `scripts/fetch-fixture.sh tca` and\n`scripts/fetch-fixture.sh swift-log`.\n\n```\nclaude-xcindex/\n├── .claude-plugin/plugin.json     # plugin manifest\n├── .mcp.json                      # MCP server registration\n├── bin/run                        # launcher\n├── service/                       # Swift MCP server\n├── skills/                        # refactor-plan, find-refs, blast-radius, rename\n├── agents/swift-refactor-specialist.md\n├── commands/                      # /xcindex-setup, /xcindex-status\n├── hooks/                         # session-start.sh, post-edit.sh, pre-grep.sh\n├── scripts/                       # dev-only: build.sh, fixtures, benchmarks\n└── Makefile                       # dev task runner (build, test, lint, format)\n```\n\nPRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Please open an\nissue to discuss architectural changes first.\n\n---\n\n## Why it's faster than grep\n\nClaude's default answer to \"where is `UserService` used?\" is `ripgrep` —\n40 noisy textual matches, 8 full files read to disambiguate. Expensive in\ntokens, imprecise in results. Xcode already solved this: every build\nwrites a full semantic index to DerivedData, and Apple's\n[`indexstore-db`](https://github.com/swiftlang/indexstore-db) queries it.\nThis plugin wraps those queries behind MCP tools so Claude reads only the\nlines that matter.\n\n- **~200× faster than `grep -rn`** on the same source tree, sub-millisecond\n  on warm queries.\n- **Semantic, not textual** — finds protocol witnesses, extensions, `@objc`\n  bridging, and module-scoped name collisions that `grep` can't.\n- **Up to 70% fewer files read** to answer a reference query.\n\nFull numbers and methodology in [docs/benchmarks.md](docs/benchmarks.md);\nthe mental model (freshness, DerivedData resolution, USR-first lookups) in\n[docs/how-it-works.md](docs/how-it-works.md).\n\n## Architecture\n\n```\nClaude Code\n    ↓ (MCP over stdio)\nxcindex plugin\n├── Skills          — tell Claude WHEN to use the index\n├── Hooks           — freshness warnings + nudge Claude off grep on Swift code\n├── Subagent        — isolated context for large renames\n├── Slash commands  — /xcindex-setup, /xcindex-status\n└── Swift binary    — MCP server, queries IndexStoreDB\n    ↓ (reads LMDB)\nDerivedData/Index.noindex/DataStore\n    ↑ (writes during build)\nXcode\n```\n\nOne native Swift binary, speaking MCP directly via Anthropic's\n[Swift SDK](https://github.com/modelcontextprotocol/swift-sdk). No Node\nruntime, no intermediate process.\n\n## Complementary tools\n\nThis plugin focuses on **semantic queries** over Xcode's on-disk index.\nIt is not a language server and does not build, test, or run your\nproject. Pair it with:\n\n### Anthropic's [`swift-lsp`](https://claude.com/plugins/swift-lsp)\n\nLive LSP features (completion, diagnostics, hover) backed by\nSourceKit-LSP. Different layer: `swift-lsp` is an editor-UI integration\n(no MCP tools the agent can call); `xcindex` exposes semantic queries to\nthe agent loop. They don't overlap.\n\n| | `swift-lsp` | `xcindex` |\n|---|---|---|\n| Backend | SourceKit-LSP server | `indexstore-db` reader |\n| Source of truth | live Swift source | Xcode build-time index |\n| Requires Xcode build? | No | Yes (once) |\n| Diagnostics & completion | Yes | No |\n| Hover / jump-to-definition | Yes | Definition only |\n| Agent-callable MCP tools | No (editor-UI only) | 7 tools |\n| Overrides / conformances / blast-radius | Not first-class | Yes |\n| Works on Linux / SwiftPM-only | Yes | No (DerivedData-specific) |\n| Warm query latency | LSP round-trip | sub-millisecond |\n| Freshness model | always live | hook-warned when stale |\n\n### Build & test orchestration\n\n- Apple's [`mcpbridge`](https://developer.apple.com/documentation/xcode) (ships with Xcode 26.3+) for build, test, preview, docs.\n- [`XcodeBuildMCP`](https://github.com/cameroncooke/XcodeBuildMCP) for older Xcode versions.\n\n## Other Swift symbol tools\n\nWhere `xcindex` sits relative to the closest neighbours:\n\n| | `xcindex` | [`block/xcode-index-mcp`](https://github.com/block/xcode-index-mcp) | [SwiftLens](https://github.com/swiftlens/swiftlens) |\n|---|---|---|---|\n| Backend | `indexstore-db` (direct) | `indexstore-db` (direct) | SourceKit-LSP |\n| Packaging | Claude Code plugin (skills + hooks + subagent) | Raw MCP server | Raw MCP server |\n| Runtime | Native Swift binary | Python (`uv`) + Swift service | Python 3.10+ |\n| MCP tools | 7 (find_symbol, find_references, find_definition, find_overrides, find_conformances, blast_radius, status) | 4 (load_index, symbol_occurrences, get_occurrences, search_pattern) | 15 (single-file analysis + cross-file refs/defs) |\n| Overrides / conformances | Yes | No | No |\n| Blast-radius analysis | Yes | No | No |\n| Freshness warnings | Hook-driven, per-session | None | None |\n| Status (Apr 2026) | Active | Active (~55⭐) | **Archived 2026-03-10** |\n\n`block/xcode-index-mcp` is the closest prior art — same backend, narrower\ntool surface, no plugin packaging. SwiftLens covered the same niche from\nthe SourceKit-LSP angle but [was archived in March 2026](https://github.com/swiftlens/swiftlens).\n\n## Prior art\n\n- [`apple/indexstore-db`](https://github.com/swiftlang/indexstore-db) — the query library this plugin wraps.\n- [`block/xcode-index-mcp`](https://github.com/block/xcode-index-mcp) — closest prior art, Python + Swift MCP server for Goose/Cursor.\n- [`michaelversus/SwiftFindRefs`](https://github.com/michaelversus/SwiftFindRefs) — CLI with the same core query.\n\n## Privacy\n\nRuns entirely on your local machine. No telemetry, no analytics, no\ntracking. The only network request is to GitHub to download the prebuilt\nbinary on first run. All queries run locally against Xcode's on-disk\nindex.\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 12252,
  "sha": "d92acd95ce6070ad15078b28759466a00337b47275a6f54da516dfed6f31812f",
  "repo_slug": "drewalth/claude-xcindex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_drewalth_claude_xcindex_claude_xcindex_408b0781/readme"
}