Local semantics and quality checks
Check local model preparation, actual inference and current-code search coverage separately. Cloud is not used by default.
Guide verification basis: Holmes-Kit 0.40.0 · 2026-11-05 · Installation target: latest at execution time
Choose a CLI, OS and installation mode to see the matching commands. This page does not inspect or execute on your computer.
AGY CLI ordinary integration is supported. AGY run start is refused in 0.40.0; this orchestration lesson has no executable AGY start procedure. Keep your choice, select a different CLI explicitly, or return to Basics.
Prerequisites, evidence and installation tradeoffs
Before you start
- Your own workspace and connected MCP session after the basics. Define HOLMES_CLI or PowerShell HolmesCli from the installation step in this terminal and verify its file and version.
- Network for initial public-model download or a verified offline cache
Explain the available semantic tier and search limitations with evidence.
Documented for 0.40.0 · release contracts reviewed 2026-11-04. Native evidence is the historical 0.39.0 run of 2026-11-01. Read-only binding matched for Codex and Claude in an independent macOS workspace. Claude hook events were observed but routing is unverified; Codex hooks were not observed. Native revalidation on 0.40.0 and RED/GREEN acceptance of a small governed change remain incomplete. Windows/Linux instructions have no native acceptance run.
- 1. Separate user folder
- Keeps project dependencies and global npm installation unchanged; separate versioned folder. Manage its path and updates separately; retain the folder while workspaces use it.
- 2. Project local
- Project/team versioning through a lockfile; recommended for the practice project. Changes package.json and lockfile; may introduce npm metadata to a non-Node project.
- 3. Global npm
- Convenient shared installation across projects. Check write permissions and update impact on all projects sharing this installation.
Package location and client settings are separate. Even project-local Codex wiring may change user-level settings.
Step 1 / 4
Inspect current tier and coverage
Decide whether to permit model download and local resource use.
Terminal in your workspace
node "$HOLMES_CLI" semantic-key statusTerminal in your workspace
node "$HOLMES_CLI" semantic-key statusTerminal in your workspace
node "$HolmesCli" semantic-key statusTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent claudeTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent codexTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent antigravityTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent claudeTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent codexTerminal in your workspace
node "$HOLMES_CLI" doctor --target . --agent antigravityTerminal in your workspace
node "$HolmesCli" doctor --target . --agent claudeTerminal in your workspace
node "$HolmesCli" doctor --target . --agent codexTerminal in your workspace
node "$HolmesCli" doctor --target . --agent antigravityExpected result — inspect your actual output
- Unavailable, degraded and unverified states remain visible.
If the result differs
The tier is local but current document vectors are absent.
Diagnose inference readiness separately from code-index coverage and verify retrieval quality.
What the agent does / terms
Separate preparation, verification and current document-vector coverage in doctor output.
- MCP
- The connection through which your AI calls Holmes tools.
- REQ → H-SPEC → A-SPEC → T-SPEC
- Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
- Hook / binding
- A pre/post execution check / matching this session to the intended project and server.
Step 2 / 4
Prepare the local model
Review network and disk use before running.
Terminal in your workspace
node "$HOLMES_CLI" semantic-setupTerminal in your workspace
node "$HOLMES_CLI" semantic-setupTerminal in your workspace
node "$HolmesCli" semantic-setupExpected result — inspect your actual output
- Preparation exit code and verification results are recorded; on failure, inspect graph functionality separately.
If the result differs
A network or sharp native-module error occurs.
Inspect the doctor diagnosis. For blocked scripts, review the installed dependency version, approve and rebuild only that package, then retry preparation.
What the agent does / terms
Read semantic-setup results and record failures. init may also attempt preparation; to opt out, apply HOLMES_SKIP_MODEL_INSTALL=1 to both installation and init.
- MCP
- The connection through which your AI calls Holmes tools.
- REQ → H-SPEC → A-SPEC → T-SPEC
- Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
- Hook / binding
- A pre/post execution check / matching this session to the intended project and server.
Step 3 / 4
Run offline inference
Wait for completion and inspect exit status.
Terminal in your workspace
node "$HOLMES_CLI" semantic-checkTerminal in your workspace
node "$HOLMES_CLI" semantic-checkTerminal in your workspace
node "$HolmesCli" semantic-checkExpected result — inspect your actual output
- Actual inference success or a concrete failure is recorded.
If the result differs
The cache changed or inference times out.
Verify or repair the cache with semantic-setup and recheck; do not label mere preparation as an active tier.
What the agent does / terms
Inspect validation of a finite normalized 1024-dimensional vector. Do not transfer another machine’s success to this machine.
- MCP
- The connection through which your AI calls Holmes tools.
- REQ → H-SPEC → A-SPEC → T-SPEC
- Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
- Hook / binding
- A pre/post execution check / matching this session to the intended project and server.
Step 4 / 4
Check retrieval with a real question
Choose a real maintenance question without naming the file.
Ask your agent
Locate the code responsible for this behavior without a filename. Separate lexical candidates and semanticAlternates and verify actual functions and calls. Do not configure a cloud key.Expected result — inspect your actual output
- Each candidate has actual evidence and retrieval limitations are stated.
If the result differs
A semantically similar file with a different responsibility ranks highly.
Read code and discard it. If cloud use is needed, first obtain separate consent for transmitted content, cost and request limits.
What the agent does / terms
Inspect existing cloud opt-in with semantic-key status. If this local-only task has cloud enabled, confirm the choice before transmitting; never change keys automatically.
- MCP
- The connection through which your AI calls Holmes tools.
- REQ → H-SPEC → A-SPEC → T-SPEC
- Requirement → high-level design → implementation design → test specification. Use actual IDs returned by the tools.
- Hook / binding
- A pre/post execution check / matching this session to the intended project and server.
Apply to your project
Local vector validation and retrieval quality are separate. This guide claims no recall metric or performance gain on your code; verify with actual queries.
Related case ↗Continue with your project
Use Adoption for existing code without specs, or Requirements when specifications already exist. Other workflows require their stated prerequisites.