Agent Setup Guide

Instructions for AI agents (Claude Code, Cursor, Copilot, etc.) to set up IndexRaccoon in a project.

In this guide: user = the human, agent = you (the AI assistant). Front-load all questions to the user first, then run the setup while they get coffee.

Phase 1: Ask the user

Ask all questions upfront so the user can answer once:

"Would you like to install IndexRaccoon for semantic code search?" (skip if already installed)
"Which OS are you on?" (macOS/Linux or Windows)
"Which embedding provider?"
- Ollama -- free, runs locally, no API key needed. Ask if Ollama is already installed; if not, it will be installed in Phase 4.
- OpenAI -- requires API key from platform.openai.com. Ask the user to get their key now.
- Voyage -- requires API key from dash.voyageai.com. Ask the user to get their key now.

Note: API keys are stored in clear text in .indexraccoon/.env. The .indexraccoon/ directory is auto-added to .gitignore by indexraccoon init.

Phase 2: Install

macOS / Linux

$ curl -fsSL https://get.indexraccoon.com/sh | bash

Windows

$ irm https://get.indexraccoon.com/ps1 | iex

Phase 3: Initialize

Prerequisite: authenticate

$ indexraccoon login

$ indexraccoon init --type <unity|web|minimum>

Creates .indexraccoon/ with config. Auto-added to .gitignore.

Phase 4: Set up embedding provider

Ollama (free, local)

Install Ollama:

macOS / Linux

$ curl -fsSL https://ollama.com/install.sh | sh

Windows: download from ollama.com/download

Pull the embedding model:

$ ollama pull nomic-embed-text

Ollama is the default provider -- no further config needed.

OpenAI

Get an API key from platform.openai.com/api-keys, then:

$ indexraccoon config set provider openai

$ indexraccoon config set-key <your-api-key>

Or set manually in .indexraccoon/.env: OPENAI_API_KEY=sk-...

Voyage

Get an API key from dash.voyageai.com/api-keys, then:

$ indexraccoon config set provider voyage

$ indexraccoon config set-key <your-api-key>

Or set manually in .indexraccoon/.env: VOYAGE_API_KEY=pa-...

Phase 5: Initial index

$ indexraccoon index

The first index takes 2-10 minutes depending on project size. This is expected -- do not kill the process. After the first index, subsequent queries auto-index incrementally and are fast.

Phase 6: Agent instructions

$ indexraccoon agent

Outputs IndexRaccoon usage instructions for your agent config. Ask the user: "Would you like me to add these instructions to your CLAUDE.md (or equivalent agent config file)?"

Phase 7: Done

Setup complete. Summary of what was configured:

Installed IndexRaccoon CLI
Authenticated and initialized the project
Configured the embedding provider
Built the initial index
Generated agent instructions

Run a test query to showcase the tool to the user -- pick something relevant to the project:

$ indexraccoon query "how does the main system work"

Returns semantically relevant code snippets ranked by relevance score.

Quick reference

Run indexraccoon --help for the full command list. Key commands:

Command	Description
query "..."	Find code by meaning
trace "Method" --reverse	Find callers
trace "Method"	Find callees
flow "A" "B"	Find execution paths
signature "Method"	Get full signatures
git "..." --days 14	Search commit history
index	Force re-index
agent	Generate agent instructions