Holmes LabAgentic Software Engineering Architect

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

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 the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" semantic-key status
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" semantic-key status
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" semantic-key status
Terminal in the confirmed projectClaude Code CLI · macos

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent claude
Terminal in the confirmed projectCodex CLI · macos

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent codex
Terminal in the confirmed projectAGY CLI · macos

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent antigravity
Terminal in the confirmed projectClaude Code CLI · linux

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent claude
Terminal in the confirmed projectCodex CLI · linux

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent codex
Terminal in the confirmed projectAGY CLI · linux

Terminal in your workspace

node "$HOLMES_CLI" doctor --target . --agent antigravity
Terminal in the confirmed projectClaude Code CLI · windows

Terminal in your workspace

node "$HolmesCli" doctor --target . --agent claude
Terminal in the confirmed projectCodex CLI · windows

Terminal in your workspace

node "$HolmesCli" doctor --target . --agent codex
Terminal in the confirmed projectAGY CLI · windows

Terminal in your workspace

node "$HolmesCli" doctor --target . --agent antigravity

Expected result — inspect your actual output

  • Unavailable, degraded and unverified states remain visible.
A manual learning note, not automatic verification of your workspace.
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 the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" semantic-setup
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" semantic-setup
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" semantic-setup

Expected result — inspect your actual output

  • Preparation exit code and verification results are recorded; on failure, inspect graph functionality separately.
A manual learning note, not automatic verification of your workspace.
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 the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" semantic-check
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" semantic-check
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" semantic-check

Expected result — inspect your actual output

  • Actual inference success or a concrete failure is recorded.
A manual learning note, not automatic verification of your workspace.
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.

Paste into your AI CLIShared

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.
A manual learning note, not automatic verification of your workspace.
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.