60-Second Quickstart

# Install globally (or use npx)
npm install -g mikoshi

# Index your project — everything stays local
cd ~/your-project
mikoshi index .

# Understand your code — no LLM needed
mikoshi explain mergeScores        # callers, callees, imports, tests
mikoshi impact auth.js             # blast radius: every affected function
mikoshi search . "retry logic"     # BM25 + semantic hybrid search
mikoshi diff-review                # graph-verified PR review

# Machine-readable output for scripts & CI
mikoshi explain mergeScores --json
mikoshi impact auth.js --json

Or try the self-demo (indexes the current repo and runs 3 showcase queries):

npx mikoshi demo

Why Mikoshi?

| | Mikoshi | Cloud search tools | |---|---|---| | Privacy | 100% local — zero network calls during search/index | Sends code to cloud | | Call graph | Real call/import edges with confidence scores | Embeddings only | | explain | Shows callers, callees, imports, tests — no LLM needed | N/A | | impact | Blast radius: "change X → these 14 functions break" | N/A | | diff-review | Graph-verified PR review — --strict = zero hallucination | LLM-only | | MCP | Built-in MCP server for Claude, Cursor, Copilot | Varies | | Cost | Free forever | Per-seat pricing |

Core Commands

Index

mikoshi index .                  # first run: AST parse + embed (local ONNX)
mikoshi watch                    # live re-index on file save

Understand

mikoshi explain <symbol>         # definition, callers, callees, imports, tests
mikoshi impact <symbol|file>     # transitive dependents + affected tests
mikoshi diff-review              # graph-verified review of git diff (--strict default)
mikoshi diff-review --staged     # review only staged changes

Search

mikoshi search . "query" [k]     # 7-stage retrieval: BM25 + semantic + smart ranking

Agent

mikoshi run "summarize this repo"
mikoshi run --print --max-turns 6 "refactor auth module"

Health

mikoshi doctor                   # node, config, index, graph, embeddings, staleness

MCP Integration

Mikoshi ships a built-in MCP server over stdio. Works with Claude Code, Cursor, VS Code Copilot, Windsurf, or any MCP-compatible client.

mikoshi-mcp                      # starts stdio MCP server

Tools exposed via MCP:

| Tool | Description | |---|---| | Mikoshi Context-Engine | Full 7-stage retrieval pipeline | | get_code_web | Structured symbol neighborhood with evidence + confidence | | explain_symbol | Callers, callees, imports, tests for a symbol | | impact_analysis | Blast radius: transitive dependents + affected tests | | diff_review | Graph-verified git diff review |

Claude Code / Claude Desktop

Add to ~/.claude/claude_desktop_config.json or project .mcp.json:

{
  "mcpServers": {
    "mikoshi": { "command": "mikoshi-mcp", "args": [] }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "mikoshi": {
      "command": "mikoshi-mcp",
      "args": []
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "mikoshi": {
      "type": "stdio",
      "command": "mikoshi-mcp",
      "args": []
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mikoshi": {
      "command": "mikoshi-mcp",
      "args": []
    }
  }
}

No Native Tool Calls? Use Evidence Packs

Tool calling depends on the host client (mode, permissions, local stdio policy) — not just the model. If your AI editor doesn't support MCP, or your model can't emit tool calls, Mikoshi still works.

The --clip flag outputs a compact JSON evidence pack you can paste into any model:

# Search → evidence pack → clipboard
mikoshi search . "retry logic" --clip | pbcopy

# Explain a symbol → evidence pack → clipboard
mikoshi explain mergeScores --clip | pbcopy

# Impact analysis → evidence pack
mikoshi impact auth.js --clip | pbcopy

# Diff review → evidence pack
mikoshi diff-review --clip | pbcopy

Then paste into ChatGPT, Claude, Gemini, or any model:

Here is grounded evidence from my codebase. Answer based on this context: ⌘V

Evidence packs include:

• File paths, line numbers, and code snippets
• Call graph relationships (callers, callees, imports)
• Confidence scores for every edge
• Structured JSON that models parse easily

mikoshi doctor detects MCP and tool availability and prints fixes:

mikoshi doctor
# ✅ MCP server: /opt/homebrew/bin/mikoshi-mcp
# ⚠️  MCP config: no Mikoshi MCP config found
#    Fix: mikoshi init
#    Or paste into any model with: mikoshi search . "query" --clip

ACP Integration

mikoshi --acp                    # ACP server over stdio
mikoshi acp setup .              # generate config for ACP-compatible editors

How It Works

Source → AST Parser → Hierarchical Chunks (file/class/function/method)
     → Local ONNX Embeddings (all-MiniLM-L6-v2, no API key)
     → Dependency Graph (imports + call edges + symbol table)

Query → Query Understanding → Multi-Query Expansion
     → BM25 + Semantic Hybrid Search
     → 6-Factor Smart Ranking (semantic, structural, recency, frequency, type, task)
     → Reranking → Context Enrichment + Web Neighborhood
     → Token-Budget Compression → AI-Readable Output

Every call edge carries a confidence score (high / medium / low) so the AI — and you — know what's verified vs. heuristic.

Configuration

mikoshi settings                 # interactive config (shell, auto-updates, provider)
mikoshi login                    # optional — for cloud features

Environment variables: | Variable | Default | Description | |---|---|---| | MIKOSHI_INDEX_ROOT | ~/.mikoshi | Where indexes are stored | | MIKOSHI_EMBEDDINGS_PROVIDER | local | local (ONNX) or openai | | MIKOSHI_EMBED_MODEL | all-MiniLM-L6-v2 | Embedding model |

Models (for agent/chat):

/models  # inside interactive shell
# Providers: openai, anthropic, minimax, kimi
# API keys stored per provider, locally

Developer

npm install
npm test                         # runs all tests
mikoshi doctor .                 # validate install + index health

Provenance

See PROVENANCE.md for implementation provenance and design constraints.