[bonnyr]

Requested by Bonny

Summary

Adds an indexPath config option so a project's index can live outside the repository, for example under ~/.local/share/..., while keeping per-project indexes and worktree sharing. Today the index location is fixed: <repo>/.claude/index/ (or the host's equivalent) for scope: "project", or one shared global index for scope: "global". The indexer already accepts an index path override internally, but the CLI, MCP server, watcher, background worker, auto-index and index_status each resolve the path themselves, so it can't be used.

Changes

• indexPath in the config schema: absolute or ~/-prefixed, with {env:NAME} substitution.
• One resolver in src/config/paths.ts, used by the indexer, the file watcher, the background worker, auto-index, MCP diagnostics and index_status.
• With scope: "project", stored paths stay root-relative, so linked worktrees that use the same configuration share the index exactly as they share .claude/index/ today. The main checkout owns the index, and the existing inherited-index safety checks (no force rebuild or recovery from a linked worktree) still apply.
• index_status now reads the runtime config, so it honours --config like the rest of the server. Previously it read the default config locations.
• Docs: new "Index location" section in docs/configuration.md.

Testing

• Unit tests added: tests/configured-index-path.test.ts (5 tests). They fail without the change and pass with it.
• Manual testing performed: used through --config on a ~1,000-file repo with linked worktrees. The index is outside the repo, worktree changes show up through the watcher, and git status stays clean.
• Build passes (npm run build:ts). The native module was not rebuilt, since native/ is unchanged since 0.38.2 and the prebuilt 0.38.2 binary was used.
• Typecheck passes (npm run typecheck)
• Tests pass (npm run test:run): 3,086 passed. The 2 failures are in tests/watcher-snapshot-reconciler.test.ts, which also fails intermittently on unpatched main on this machine (WSL2, 1 to 3 of its 10 tests per run).
• Lint passes (npm run lint)

Release Labels

I can't add labels from a fork. Suggested: feature, semver:minor.

Related Issues

None. I searched issues and PRs for an index-path request first.

🤖 Generated with Claude Code

[Helweg]

Automated PR review

Reviewed head ff5a3ccb245258298ef2321a89ecb30d2110e6b9 against base 47bf78b7b08564bf394cd74c0a647672481976fb. Checked all 10 changed files, config loading/merging, index ownership and rebuild guards, watcher/worker path propagation, status consumers, evaluation callers, documentation, and the five added tests.

Finding

P2 — Evaluation --reindex still clears the default directory, not the configured index. At src/indexer/index.ts:1393, the indexer now opens config.indexPath, but runEvaluation still calls clearIndexRoot(projectRoot, effectiveConfig.scope). That helper only resolves the old default locations. With an existing configured index, eval run --reindex therefore leaves that index intact and deletes an existing default index instead. The subsequent indexer.index() is incremental; changing the embedding model can still hit the compatibility rejection despite requesting a rebuild. Update the evaluation reset path to honor the effective configured location with the appropriate ownership/shared-index safeguards, and cover an existing configured index plus an untouched default index in a regression test. The added tests do not exercise this caller.

Observed CI and limits

• CI and Release Label Check: action_required; no build/typecheck/lint/test success observed for this head.
• Release Drafter: successful; not behavioral validation.
• Static review and observed CI only; candidate code/tests were not executed. Author-reported test results were not independently verified.