Skip to main content

Claude Code Setup

With the quickstart confirmed working, wiring Shaktiman into Claude Code takes three steps. After this, every Shaktiman MCP tool becomes available to your agent automatically.

Paths

The steps below use absolute paths. Replace /absolute/path/to/... with your own. You can get the absolute path of your built shaktimand binary with:

realpath ./shaktimand    # Linux
# or
echo "$(pwd)/shaktimand" # any POSIX shell

1. Create .mcp.json in your project root​

{
  "mcpServers": {
    "shaktiman": {
      "command": "/absolute/path/to/shaktimand",
      "args": ["/absolute/path/to/your/project"],
      "env": {
        "SHAKTIMAN_LOG_LEVEL": "WARN"
      }
    }
  }
}
  • command is the absolute path to the shaktimand binary.
  • args is a single-element array containing the absolute path to the project root you want indexed.
  • env.SHAKTIMAN_LOG_LEVEL controls structured-log verbosity. Use "DEBUG" while wiring things up, then drop back to "WARN" or remove the key.

2. Smoke-test the daemon before restarting Claude Code​

Before you restart Claude Code, confirm shaktimand can start with the exact arguments Claude Code will pass. This catches path typos and permission issues in seconds, instead of after a full Claude Code restart:

/absolute/path/to/shaktimand /absolute/path/to/your/project < /dev/null

You should see startup log lines (lock acquisition, watcher starting) and the process should exit cleanly when stdin closes. If it errors, fix the .mcp.json path or permissions before moving on — Claude Code will hit the same error silently on restart.

3. Restart Claude Code​

Open a new Claude Code session in the project. On first launch, shaktimand starts, acquires the project lock, and begins cold-indexing in the background. The first session may experience "index warming" briefly; queries work at Level 1 (keyword + structural) while the index fills.

4. Confirm the tools are registered​

In Claude Code, run:

/mcp

You should see shaktiman listed as a connected MCP server. The seven tools (summary, search, context, symbols, dependencies, diff, enrichment_status) are now available to the agent.

5. Run your first tool call​

Ask the agent to orient itself:

"Give me a one-line summary of this codebase."

The agent will call mcp__shaktiman__summary. You'll see something like:

Files: 4213 | Chunks: 58104 | Symbols: 41220
Languages: typescript (3210), go (901), python (102)
Embeddings: 0%

That's the confirmation.

About that Embeddings: 0%

The daemon-launched indexer honors embedding.enabled, which defaults to true — but Ollama also needs to be installed and running with an embedding model pulled (ollama pull nomic-embed-text). If Ollama isn't reachable, the circuit breaker opens and you'll see Embeddings: 0%; keyword + structural search still work.

If you ran the quickstart without --embed, your CLI-populated index has no embeddings either, and you'll see 0% here until the daemon catches up. See Embeddings for the full picture.

From here on, Claude Code will reach for Shaktiman whenever it helps — ranked search, budget-fitted context, dependency traversal, and so on.

What if it didn't work?​

  • shaktimand failed to start → check .shaktiman/shaktimand.log in your project.
  • Tools don't appear under /mcp → verify the command path in .mcp.json points at a real executable (ls -l /absolute/path/to/shaktimand).
  • Searches return nothing → the index may still be warming. Ask the agent to call enrichment_status or see Troubleshooting → Indexing stuck.

Next​