Workspace & Code Locations

Start a coding task with project purpose and the current objective, then locate code with file and line evidence.

Bind the workspace

hnindex init --mcp claude --cwd /absolute/project
# Project binding is automatic for claude, cursor-project and vscode.
hnindex init --mcp windsurf --project-root /absolute/project

Project installs set HNINDEX_PROJECT_ROOT. Global installs follow current MCP client roots unless explicitly bound. Selection prefers explicit project/path, configured root, client roots, then an indexed server cwd. Multiple roots require explicit selection. Regenerate machine-specific configuration after moving a checkout.

Start and remember a task

workspace_context(path: "/absolute/project")
// If not indexed, initialize TS/JS locations offline:
index_code_graph(path: "/absolute/project", project_name: "my-app")
workspace_context(project_name: "my-app", task: "Fix authentication", session_id: "agent-1")

workspace_context returns purpose with source attribution, live document excerpts, indexed directories, Git state and index readiness. The task is declared by the user/agent, persisted in SQLite per project/session and recalled when task is omitted. Use distinct session IDs for concurrent agents; the default ID is shared. Clear with clear_task: true. hnindex does not observe every conversation or infer intent from Git.

MCP initialization instructions and knowledge://workspace expose this workflow. The client decides when to call tools/read resources. Install optional guidance with hnindex init-skill --target claude.

Locate before editing

locate_code(query: "authenticate")
locate_code(symbol: "authenticate", file_pattern: "src/auth.ts")
locate_code(query: "src/auth.ts")
locate_code(query: "how requests authenticate", mode: "hybrid")

Auto mode tries files, symbols and local keywords without embeddings. Explicit hybrid mode uses configured semantic services/API costs. Graph-only indexing provides TS/JS locations; use index_codebase for keyword/vector chunks and other languages.

Results include paths, lines, optional signatures/excerpts, ambiguous definitions and nearby CALLS/REFERENCES. A file pattern narrows definitions; related use sites can appear in other files.

Verify freshness

• fresh: selected file matches indexed contents.
• stale: file changed; returned positions refer to the previous snapshot.
• missing_or_excluded: missing, ignored, oversized or outside root; no excerpt.
• unverified: no stored hash to compare.

Relationship freshness checks use-site/target files. Resolution describes the indexed graph; changes to barrel imports or tsconfig require graph refresh. Dynamic/external calls may be unresolved. Use index_code_graph for graph-only projects or index_file/index_codebase for full indexes, then re-locate before editing stale positions.

Use callers/find_references or smart_context for deeper context. Filesystem reads/search remain available for unavailable, stale or excluded code. Output is bounded by a cl100k_base token budget (workspace default 2500, locator 2000); narrow the query when truncated.

Full workspace reference