Skip to main content

Quickstart

After installation, the fastest way to confirm Shaktiman is working is to index one of your own projects and run a query. This path does not require Claude Code — it talks to the index directly. Once this works end-to-end, hooking up Claude Code is a three-step setup.

The commands below assume shaktiman and shaktimand are on your PATH. If they aren't, use ./shaktiman and ./shaktimand from where you built them.

1. Pick a project​

cd /path/to/your/project

Your project should contain source files in one of the supported languages.

2. Initialize the config directory​

shaktiman init .

Creates .shaktiman/shaktiman.toml (a commented sample) in your project root. Every value is optional — the defaults are good.

3. Index the project​

shaktiman index .

Progress streams to stdout: Indexing: N/M files (X%). On a modest repo (a few thousand files) this completes in under a minute. When it's done you'll see the per-language breakdown:

Indexed: 4213 files | 58104 chunks | 41220 symbols
  typescript: 3210 files
  python: 102 files
  go: 901 files
Embeddings (optional)

Add --embed to also generate vector embeddings. This requires Ollama running locally with a compatible embedding model (ollama pull nomic-embed-text). Without it, search falls back to keyword mode — still fast, still useful.

The CLI (shaktiman index) is opt-in for embeddings. The daemon-launched indexer that Claude Code triggers honors embedding.enabled (default true) instead, so once you wire up Claude Code your index will start embedding automatically. See Embeddings for the full story.

4. Confirm the index​

shaktiman status .

Prints file, chunk, symbol, and parse-error counts plus per-language file counts. A healthy first-index looks like:

  • Files, chunks, symbols all non-zero.
  • Parse errors a small fraction of total files (ideally zero; a handful is normal for mixed-language repos with exotic constructs).
  • Languages list matches what you actually have in the repo.

If any of those look off, see Troubleshooting → Empty or bad results. Otherwise, move on.

Pick a term you'd expect to find in your project — a function name, a concept, a filename. For example:

shaktiman search "error handling" --root . --format text

You should see ranked pointers: file path, line range, symbol name, score — one per line. That's the locate mode output the MCP server returns by default.

If the search returns nothing, see Troubleshooting → Empty or bad results.

6. You're done​

The index is ready. You can: