Skip to content
hnindex.Documentation
v0.16.1Website

GETTING STARTED / v0.16.1

Installation

Start with local workspace context and multilingual code navigation. Add semantic retrieval when your workflow needs it.

Requirements

  • Node.js 22 or newer and npm.
  • An MCP client such as Codex, Claude Code, Cursor, VS Code, Windsurf or Antigravity.
  • A readable project directory. SQLite storage defaults to ~/.vibe-hnindex.

Workspace context and index_code_graph do not require Qdrant, Ollama or a cloud API key. AST graph analysis uses the JS/TS compiler plus bundled Tree-sitter profiles for additional languages.

Connect your editor

cd /your/project
npx -y hnindex-cli init --mcp codex
npx -y hnindex-cli init --mcp claude

# Other project-scoped targets
npx -y hnindex-cli init --mcp cursor-project
npx -y hnindex-cli init --mcp vscode

Project-scoped targets bind HNINDEX_PROJECT_ROOT automatically. For a global configuration, either use current MCP client roots or bind a root explicitly:

npx -y hnindex-cli init --mcp windsurf --project-root /your/project

Restart or reconnect your MCP client after updating its configuration. Follow the quick start to initialize the local graph.

Codex

The Codex target writes project .codex/config.toml and binds the workspace automatically. Codex loads this file only for trusted projects. Restart or reconnect Codex after setup.

npx -y hnindex-cli init --mcp codex
npx -y hnindex-cli init-skill --target codex

The optional skill is installed in .agents/skills/use-vibe-hnindex. See the Codex MCP setup for TOML and connection checks.

Optional: semantic and hybrid retrieval

Full codebase vector indexing and semantic/hybrid search use Qdrant plus your chosen provider: Ollama, OpenAI, Voyage, Gemini or an OpenAI-compatible endpoint.

docker run -d --name hnindex-qdrant -p 6333:6333 \
  -v hnindex-qdrant:/qdrant/storage qdrant/qdrant

# For local embeddings only (Ollama installed separately):
ollama pull bge-m3:567m

Configure EMBEDDING_PROVIDER and the matching key/model in the MCP server environment. See configuration for settings. Cloud embeddings send code chunks to that provider; Ollama can keep embedding traffic local.

Verify the connection

Ask the agent to call workspace_context with the project path, then index_code_graph. Use diagnostics when troubleshooting optional embedding and Qdrant services. Do not treat a missing optional service as a prerequisite for offline graph navigation.