GETTING STARTED / v0.16.1

From a repo to useful context.

Connect MCP, initialize a local graph, then give your agent a concrete task. This offline path needs Node 22+ and a project in one of the supported AST languages.

1. Connect MCP

Run in the project directory, then restart your editor’s MCP connection:

npx -y hnindex-cli init --mcp claude
# Cursor: --mcp cursor-project
# VS Code: --mcp vscode
# Global targets: add --project-root /your/project

2. Inspect and index the workspace

The following examples are tool calls to request from your agent, not shell commands. Use an absolute path and a unique project name.

workspace_context(path: "/your/project")
index_code_graph(path: "/your/project", project_name: "my-app")

The graph stores source locations and relationships in SQLite. It requires no embedding key or Qdrant. If your repository uses other languages, use full index_codebase indexing with the configured services for keyword/vector chunks.

3. Declare the task

workspace_context(
  project_name: "my-app",
  task: "Add session expiry",
  session_id: "agent-1"
)

hnindex returns purpose documents, live Git state and index readiness. The declared task persists per project/session in SQLite. Git changes are evidence; they do not reveal your objective. Use distinct session IDs for concurrent agents.

4. Locate before editing

locate_code(project_name: "my-app", symbol: "verifySession")
locate_code(project_name: "my-app", query: "src/auth/session.ts")

Inspect paths, lines, source excerpts, ambiguity and freshness. Auto mode tries file, symbol and local keyword lookup without embeddings. Re-index changed code; use filesystem search for excluded, missing or stale results.

5. Add semantic retrieval when useful

Configure Qdrant and your embedding provider, then request index_codebase(path: "/your/project", project_name: "my-app"). Explicit locate_code hybrid mode uses these services and can incur provider costs. Switching providers/models/dimensions requires full re-indexing.