Holmes LabAgentic Software Engineering Architect

Upgrade, recovery and daily operations

Inspect installed version, running server, guidance and native trust separately.

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.
  • An operator able to review current configuration and changes

Preserve configuration, verify actual reconnection and recover failures through official routes.

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 / 6

Decide by request ID and inspect remaining authority

Read the target and subject with approve --list --target . and decide through the official operator-terminal route. The agent must not issue a grant.

Terminal in the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" approve --list --target .
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" approve --list --target .
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" approve --list --target .
Terminal in the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" approve --status --target .
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" approve --status --target .
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" approve --status --target .
Paste into your AI CLIShared

Ask your agent

Read the actual request ID and subject rather than a list number and relay them to the person. Do not execute a grant command. Distinguish denial, hold, expiry and consumption; after revocation inspect status for remaining grants.

Expected result — inspect your actual output

  • The decision matches the current request and single use, expiry and revocation are distinguished.
A manual learning note, not automatic verification of your workspace.
If the result differs

The prefix is ambiguous or the request is marked as coming from an unreleased development build.

Reread the full ID. Refile a development-build request by retrying the original official act; do not invent a generation ID.

What the agent does / terms

A grant is single-use and remains spent even if the permitted tool fails. --deny does not withdraw a live grant; use --revoke and inspect remaining authority with --status.

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 / 6

Review protected files explicitly

Inspect each changed file and ledger owner. Even under a full profile the person first stages changed spec files by their exact paths.

Paste into your AI CLIShared

Ask your agent

Before staging, list spec, evidence and provenance paths with their owning replicas. Show the exact paths requiring human approval; do not run a bulk stage or workaround script.

Expected result — inspect your actual output

  • Staging state and required human decisions are distinct for protected and product files.
A manual learning note, not automatic verification of your workspace.
If the result differs

A bulk stage reaches protected paths or another replica ledger and is refused.

Do not hand-edit ledgers or seals. Have the person stage spec paths first, then inspect the remaining scope.

What the agent does / terms

Do not sweep another replica ledger with git add -A, git add . or git commit -a. Commands that construct .ax paths at runtime are judged too. Follow the refusal code and official recovery route.

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 / 6

Record what is running

Choose the project and harness for this operation.

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

Terminal in your workspace

node "$HOLMES_CLI" runtime-binding status --workspace .
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" runtime-binding status --workspace .
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" runtime-binding status --workspace .
Paste into your AI CLIShared

Ask your agent

Compare current workspace_preflight with doctor and report installed version, loaded build, root, spec store and stale state separately.

Expected result — inspect your actual output

  • Installation and runtime state are recorded separately.
A manual learning note, not automatic verification of your workspace.
If the result differs

An old server continues responding after installation.

Restart every affected MCP server after upgrading and compare loadedBuild and diskBuild using basis_detail alongside fresh preflight. Inspect runtime-binding status and official setup --dry-run first; applying user configuration requires separate review.

What the agent does / terms

Compare doctor and workspace_preflight to record root, spec store, version and serverStale.

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 / 6

Refresh operating guidance safely

Check in the preview that project-specific rules are preserved.

Terminal in the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" guidance check --target .
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" guidance check --target .
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" guidance check --target .
Terminal in the confirmed projectShared · macos

Terminal in your workspace

node "$HOLMES_CLI" guidance refresh --target . --dry-run
Terminal in the confirmed projectShared · linux

Terminal in your workspace

node "$HOLMES_CLI" guidance refresh --target . --dry-run
Terminal in the confirmed projectShared · windows

Terminal in your workspace

node "$HolmesCli" guidance refresh --target . --dry-run

Expected result — inspect your actual output

  • Current or outdated status is clear; after applying, reload instructions in a new session.
A manual learning note, not automatic verification of your workspace.
If the result differs

Unknown edits or marker conflicts occur.

Review manually while preserving user rules, then retry; do not hide conflicts with --force.

What the agent does / terms

Run guidance check and refresh --dry-run, then apply official refresh after review.

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 5 / 6

Recover according to the actual cause

Read the error and target path; permit only the necessary change.

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
Paste into your AI CLIShared

Ask your agent

Propose recovery for the actual doctor diagnosis only. Inspect exact installed versions before approving scripts for required dependencies; do not enable a global allow-all policy.

Expected result — inspect your actual output

  • The corrected cause is linked to a post-recovery check.
A manual learning note, not automatic verification of your workspace.
If the result differs

The error repeats or a different package path was repaired.

Recheck the installation actually selected by npx and the loaded build. For approval denial follow official refusal guidance; do not build bypass scripts.

What the agent does / terms

Distinguish EPERM, scripts-blocked, abi-mismatch and build-failed. For Windows execution-policy errors use npm.cmd/npx.cmd.

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 6 / 6

Revalidate the original task

Review the original goal and remaining limitations.

Paste into your AI CLIShared

Ask your agent

After recovery, verify paths with a fresh preflight and repeat the original failing task. Separate configuration readiness, MCP binding, actual hook observations and task outcome; retain unverified items.

Expected result — inspect your actual output

  • Actual results establish whether the original failure is resolved.
A manual learning note, not automatic verification of your workspace.
If the result differs

Binding is matched but hook execution is not observed.

Keep runtime enforcement unverified and separately perform validation in a supported native session.

What the agent does / terms

Resume the original task in a fresh session and separately record permission, refusal, official recovery and normal-stop observations.

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.

Recorded Holmes Lab change

A-SPEC-101.21 restored three hidden primary links on home—Technical journey, Work and Practice—removed graph fallback JSON links and expanded Practice content. RED, regression and build records in docs/evidence/engineering-perspective are historical evidence. Running these instructions in your project is a reproduction, not that historical execution.

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.