Getting Started with SourceIndex

Hey — and thank you! You're the very first person outside the team to try SourceIndex, and that genuinely means a lot. I'm really glad you're giving it a go.

Anything you notice along the way — good, bad, broken, or just "huh, that's weird" — would be hugely helpful to hear. No feedback is too small.

What it is

When you ask a coding agent to fix or build something, it has to find the relevant code first. By default Claude Code, opencode, and Codex do that live, in your session. SourceIndex does it ahead of time so the agent jumps straight to the right files.

Best on an existing repo you didn't fully write yourself. Not very useful on a brand-new empty project.

Install and set up

You'll need Python 3.10+ and a SourceIndex API key (starts with sk-si-). Apply for access at https://sourceindex.dev/access.

Easiest path: open this file in Claude Code, opencode, or Codex and tell it "set sourceindex up in this repo." It can run the steps for you.

If you'd rather do it by hand:

pip install sourceindex
cd /path/to/your/repo
sourceindex init             # auto-detects your agent(s)
sourceindex init claude      # set up Claude Code only
sourceindex init opencode    # set up opencode only
sourceindex init codex       # set up Codex only

It'll prompt for the key, set up some git hooks plus a "Codebase Search" section telling the agent to run sourceindex search itself (Claude Code, opencode) or an MCP server registration (Codex) for the coding agent your repo already uses (a CLAUDE.md or .claude/ means Claude Code; a .opencode/ means opencode; a .codex/ means Codex; an AGENTS.md alone means both opencode and Codex; none of those means Claude Code), and scan your repo. A few minutes, once per repo. You can also name several at once (sourceindex init claude opencode codex), and it's safe to re-run init later to add another agent. If you don't have a CLAUDE.md (Claude Code) or AGENTS.md (opencode, Codex) yet, run /init in your agent first.

To replace a rotated or expired key later:

sourceindex api-key set

That prompts for the new key and persists it as your user-level default. New repos and repos without a local override will use it automatically. For automation, use sourceindex api-key set --from-env with SOURCEINDEX_API_KEY already set, pass --api-key sk-si-..., or pass the key positionally: sourceindex api-key set sk-si-....

To set a repo-local override:

sourceindex api-key set --local

Explicit environment variables still win, and a repo-local key overrides the global default.

Day-to-day

Nothing. Open the repo in Claude Code, opencode, or Codex as usual — it'll use SourceIndex on its own.

If something looks off

sourceindex doctor

One screen: whether your key is accepted, whether the backend is reachable, whether this repo has an index and when it was last refreshed, whether the git and agent hooks are in place and actually fire, which coding agents are set up in this repo, and a live search. Every line marked FAIL comes with the command that fixes it. --skip-search leaves out the one check that spends model calls; --json prints the checks as data.

Feedback I'd love

• Did sourceindex init finish cleanly?
• Does the agent feel different? Even "I can't tell" is useful.
• Anything in this doc that didn't land.

More about the project lives at https://sourceindex.dev, and you can reach us any time at hi@sourceindex.dev.

Thanks!