{"id":49007607,"url":"https://github.com/drewalth/claude-xcindex","last_synced_at":"2026-04-25T20:03:24.334Z","repository":{"id":352285395,"uuid":"1214064984","full_name":"drewalth/claude-xcindex","owner":"drewalth","description":"MCP bridge to Xcode's SourceKit index for Claude Code. Semantic Swift/ObjC symbol lookups via indexstore-db — the same library SourceKit-LSP uses. Find references, overrides, conformances, and blast radius without falling back to grep.","archived":false,"fork":false,"pushed_at":"2026-04-18T21:04:28.000Z","size":8684,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T21:17:08.523Z","etag":null,"topics":["claude","claude-code","developer-tools","indexstore-db","mcp","objective-c","sourcekit","swift","symbol-lookup","xcode"],"latest_commit_sha":null,"homepage":"https://drewalth.github.io/claude-xcindex/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drewalth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T04:37:20.000Z","updated_at":"2026-04-18T21:04:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/drewalth/claude-xcindex","commit_stats":null,"previous_names":["drewalth/claude-xcindex"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/drewalth/claude-xcindex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fclaude-xcindex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fclaude-xcindex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fclaude-xcindex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fclaude-xcindex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drewalth","download_url":"https://codeload.github.com/drewalth/claude-xcindex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewalth%2Fclaude-xcindex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32274987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","developer-tools","indexstore-db","mcp","objective-c","sourcekit","swift","symbol-lookup","xcode"],"created_at":"2026-04-18T21:08:32.246Z","updated_at":"2026-04-25T20:03:24.327Z","avatar_url":"https://github.com/drewalth.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Hero](https://raw.githubusercontent.com/drewalth/claude-xcindex/main/assets/hero.png)\n\n# claude-xcindex\n\n#### Semantic Swift/ObjC symbol lookups for Claude Code — powered by Xcode's on-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\n\u003e ⚡ **Sub-ms warm queries** · 🎯 **~200× faster than `grep`** · 📉 **Up to 70% fewer files read**\n\n---\n\nA [Claude Code](https://claude.com/claude-code) plugin that gives Claude\nsemantic access to Xcode's on-disk symbol index. Refactors, reference\nlookups, and impact analysis on Swift/ObjC projects stop falling back to\n`grep`-and-read-file — and start hitting the same library SourceKit-LSP\nuses.\n\n## ✨ Features\n\n- **Lightning fast.** Sub-millisecond warm queries after the first call — roughly 200× faster than `grep -rn` on the same source tree.\n- **Semantic, not textual.** USR-authoritative references, overrides, conformances, blast-radius. Finds what `grep` can't — protocol witnesses, extensions, `@objc` bridging, module-scoped name collisions.\n- **Zero re-indexing.** Reads the same `IndexStoreDB` Xcode writes during build. No daemon, no second copy of your codebase.\n- **Honest about freshness.** Warns at session start if source is newer than the index. Annotates results in files Claude edited locally. Never builds on your behalf.\n\n→ Full numbers, methodology, and per-symbol precision in [docs/benchmarks.md](docs/benchmarks.md).\n\n## 🧠 Why\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. Apple's\n[`indexstore-db`](https://github.com/swiftlang/indexstore-db) library\nqueries it. This plugin wraps those queries behind MCP tools so Claude\nreaches for the index instead of grep — and reads only the lines that\nmatter.\n\n## 🔧 How\n\n```\nClaude Code\n    ↓ (MCP over stdio)\nclaude-xcindex 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→ Full mental model (freshness, DerivedData resolution, USR-first lookups)\nin [docs/how-it-works.md](docs/how-it-works.md).\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 \u0026 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## 🛠 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\u003e [!NOTE]\n\u003e **Marketplace submission pending.** `claude-xcindex` is awaiting approval\n\u003e for the official Anthropic plugin marketplace. In the meantime, install\n\u003e it by adding this repo as a local marketplace — same plugin, one extra\n\u003e step.\n\nFrom inside Claude Code:\n\n```\n/plugin marketplace add drewalth/claude-xcindex\n/plugin install claude-xcindex@claude-xcindex-local\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,\nrun `./bin/xcindex-doctor`.\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall from a local clone\u003c/summary\u003e\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 \u0026\u0026 swift build -c release\n```\n\nThen in Claude Code:\n\n```\n/plugin marketplace add /absolute/path/to/claude-xcindex\n/plugin install claude-xcindex@claude-xcindex-local\n```\n\nThe launcher detects the from-source build at\n`service/.build/release/xcindex` and symlinks it instead of downloading.\n\u003c/details\u003e\n\n## 🚀 Usage\n\nOnce installed, the skills trigger automatically based on what you ask.\n\n**Natural-language triggers:**\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**Explicit:** `/xcindex-status` checks index freshness and reports which\nfiles have been edited since the last build.\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## 🤝 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); `claude-xcindex` exposes semantic\nqueries to the agent loop. They don't overlap.\n\n| | `swift-lsp` | `claude-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 \u0026 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 \u0026 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\nIf you've already looked at the broader Swift-MCP space, here's where\n`claude-xcindex` sits relative to the closest neighbours:\n\n| | `claude-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## 🩺 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\n./build.sh --debug          # debug build\ncd service \u0026\u0026 swift test    # run tests\n```\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└── build.sh\n```\n\nPRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Please open an\nissue to discuss architectural changes first.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewalth%2Fclaude-xcindex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrewalth%2Fclaude-xcindex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewalth%2Fclaude-xcindex/lists"}