{ "markdown": "# goindexer\n\n

\n \"goindexer\"\n

\n\n\n## What is goindexer?\nFinding the right code in a large codebase is hard. Grep finds exact strings. IDE search finds symbols. But what about *concepts*? \"Where do we handle authentication errors?\" or \"Show me the OTP validation logic\" — those questions need semantic understanding. I built **goindexer** to solve exactly that: semantic code search that runs entirely on your machine and plugs into your favorite AI tools via MCP (Model Context Protocol).\n\ngoindexer is an MCP server that indexes your codebase and exposes semantic search, grep, file reading, structure listing, and symbol reference finding. It's designed to work with Cursor, Claude Desktop, Gemini CLI, or any MCP client. Everything runs locally: tree-sitter for parsing, Ollama for embeddings, SQLite for vector storage. No cloud APIs, no API keys.\n\nThe motivation was to save on some tokens and speed up the search process for cli tools like claude/codex/gemini and vscode. They usually 'grep search' for patterns and then read the context around the match. goindexer can do that in one go which saves on tokens and time.\n\n\n## Prerequisites\n\n- [Ollama](https://ollama.com/) running with an embedding model:\n\n ```bash\n ollama pull qwen3-embedding:4b\n ollama serve\n ```\n\n## Build\n\n```bash\ncd go\ngo build -o bin/goindexer ./cmd/goindexer\n```\n\n## Usage\n\n### CLI\n\n```bash\n# Index a codebase, then start MCP server\ngoindexer --path /path/to/project --index --watch\n\n# Start server only (index via MCP tools)\ngoindexer --path /path/to/project --watch\n```\n\n| Flag | Description |\n|------|-------------|\n| `--path` | Index root path (required for indexing). Falls back to `SOURCE_INDEX_WORKSPACE` or discovers `.goindexer` from cwd. |\n| `--index` | Run full index before starting server |\n| `--watch` | Watch for file changes and re-index in background |\n\n### MCP Server\n\nThe server exposes tools over stdio (MCP transport). Use with Cursor, Claude Desktop, or any MCP client.\n\n## Configuration\n\nAll settings via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SOURCE_INDEX_OLLAMA_URL` | `http://localhost:11434` | Ollama API URL |\n| `SOURCE_INDEX_EMBED_MODEL` | `qwen3-embedding:4b` | Embedding model name |\n| `SOURCE_INDEX_EMBED_DIM` | `2560` | Embedding dimension *(must match model)* |\n| `SOURCE_INDEX_BATCH_SIZE` | `32` | Batch size for embedding requests |\n| `SOURCE_INDEX_MAX_FILE_SIZE` | `1048576` | Max file size in bytes (1MB) |\n| `SOURCE_INDEX_MAX_CHUNK_TOKENS` | `4096` | Max tokens per chunk |\n| `SOURCE_INDEX_MIN_CHUNK_TOKENS` | `64` | Min tokens per chunk |\n| `SOURCE_INDEX_EXTRA_EXCLUDES` | — | Comma-separated globs to exclude |\n| `SOURCE_INDEX_WORKSPACE` | — | Workspace path when `--path` not set |\n\n### Embedding models\n\nDifferent models require different config. Set `SOURCE_INDEX_EMBED_DIM` to match the model's output dimension:\n\n| Model | Embed dim |\n|-------|-----------|\n| `qwen3-embedding:4b` | 2560 |\n| `nomic-embed-text` | 768 |\n\nSwitching to a model with a different dimension requires deleting the index and re-indexing.\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `index_codebase` | Index the codebase. Call first before search. |\n| `get_index_status` | Check indexing progress (idle, running, completed, failed). |\n| `search_codebase` | Semantic search over indexed code. |\n| `grep_search` | Regex search over files. |\n| `read_file_context` | Read file contents with optional line range. |\n| `list_structure` | Directory tree or symbols. Mode: `tree` or `symbols`. |\n| `find_references` | Find all references to a symbol. |\n| `delete_index` | Delete the index and clear all data. |\n\n## MCP Client Configuration\n\nAdd goindexer as an MCP server in your preferred client. Replace `/path/to/goindexer/bin/goindexer` with the path to your built binary (e.g. `$HOME/dev/goindexer/go/bin/goindexer`), or add `go/bin` to your PATH.\n\n### Codex\n\nConfig lives in `~/.codex/config.toml` (or project-scoped `.codex/config.toml` for trusted projects). Use the CLI or edit the file directly.\n\n**CLI:**\n\n```bash\ncodex mcp add goindexer --env SOURCE_INDEX_WORKSPACE=/path/to/your/project -- /path/to/goindexer/bin/goindexer --path /path/to/your/project --watch\n```\n\n**config.toml:**\n\n```toml\n[mcp_servers.goindexer]\ncommand = \"/path/to/goindexer/bin/goindexer\"\nargs = [\"--path\", \"/path/to/your/project\", \"--watch\"]\ncwd = \"/path/to/your/project\"\n\n[mcp_servers.goindexer.env]\nSOURCE_INDEX_OLLAMA_URL = \"http://localhost:11434\"\nSOURCE_INDEX_EMBED_MODEL = \"qwen3-embedding:4b\"\n```\n\nFor project-specific config, create `.codex/config.toml` in your project root and use the project path. In the Codex IDE, use MCP settings → Open config.toml.\n\n### Claude Code (CLI)\n\nClaude Code uses the `claude mcp add` CLI. Options must come before the server name; `--` separates the name from the command.\n\n**Project scope** (creates `.mcp.json` in project root, shared with team):\n\n```bash\nclaude mcp add --transport stdio --scope project goindexer -- /path/to/goindexer/bin/goindexer --path /path/to/your/project --watch\n```\n\n**User scope** (stored in `~/.claude.json`, available across projects):\n\n```bash\nclaude mcp add --transport stdio --scope user goindexer -- /path/to/goindexer/bin/goindexer --path /path/to/your/project --watch\n```\n\n**With env vars:**\n\n```bash\nclaude mcp add --transport stdio --scope project --env SOURCE_INDEX_EMBED_MODEL=qwen3-embedding:4b goindexer -- /path/to/goindexer/bin/goindexer --path /path/to/your/project --watch\n```\n\nVerify with `claude mcp list` or `/mcp` inside Claude Code.\n\n### Claude Desktop\n\nConfig file location:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux:** `~/.config/Claude/claude_desktop_config.json`\n\nOr: Settings → Developer → Edit Config.\n\n```json\n{\n \"mcpServers\": {\n \"goindexer\": {\n \"command\": \"/path/to/goindexer/bin/goindexer\",\n \"args\": [\"--path\", \"/path/to/your/project\", \"--watch\"],\n \"env\": {\n \"SOURCE_INDEX_OLLAMA_URL\": \"http://localhost:11434\",\n \"SOURCE_INDEX_EMBED_MODEL\": \"qwen3-embedding:4b\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop after editing. Look for the hammer icon (🔨) to confirm tools are loaded.\n\n### VS Code\n\nConfig in `.vscode/mcp.json` (workspace) or user profile. Command Palette: **MCP: Open User Configuration** or **MCP: Open Workspace Folder MCP Configuration**.\n\n```json\n{\n \"servers\": {\n \"goindexer\": {\n \"type\": \"stdio\",\n \"command\": \"/path/to/goindexer/bin/goindexer\",\n \"args\": [\"--path\", \"${workspaceFolder}\", \"--watch\"],\n \"env\": {\n \"SOURCE_INDEX_OLLAMA_URL\": \"http://localhost:11434\",\n \"SOURCE_INDEX_EMBED_MODEL\": \"qwen3-embedding:4b\"\n }\n }\n }\n}\n```\n\nUse `${workspaceFolder}` so each workspace uses its own path. Ensure the goindexer binary is on your PATH or use an absolute path.\n\n---\n\n## Gemini CLI Extension\n\n### Install\n\n```bash\ngemini extensions install github.com/netanelshoshanshoshan/goindexer\n```\n\nOr install a specific version:\n\n```bash\ngemini extensions install github.com/netanelshoshanshoshan/goindexer --ref v1.0.0\n```\n\n\n## Supported languages\n\nPython, Go, JavaScript, TypeScript, JSX, TSX, Rust, Java, Kotlin, C, C++, C#, Ruby, PHP, Swift, Scala.\n\n## Data layout\n\nWith `--path` set, index data lives under the project:\n\n```\nproject/\n .goindexer/\n codebase.db # SQLite + vectors\n manifest.json\n index_root.txt\n config.json # Effective config snapshot\n```\n\nWithout `--path`, data uses `~/.goindexer/` (global).\n\n", "bytes": 7662, "sha": "8dc0518e0f636550705392cfb9e22ae7efbb72ba6ac69562e7491b60b89535ff", "repo_slug": "netanelshoshan/goindexer", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_netanelshoshan_goindexer_47e29609/readme" }