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
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.
- 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 your workspace
node "$HOLMES_CLI" approve --list --target .Terminal in your workspace
node "$HOLMES_CLI" approve --list --target .Terminal in your workspace
node "$HolmesCli" approve --list --target .Terminal in your workspace
node "$HOLMES_CLI" approve --status --target .Terminal in your workspace
node "$HOLMES_CLI" approve --status --target .Terminal in your workspace
node "$HolmesCli" approve --status --target .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.
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.
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.
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 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 antigravityTerminal in your workspace
node "$HOLMES_CLI" runtime-binding status --workspace .Terminal in your workspace
node "$HOLMES_CLI" runtime-binding status --workspace .Terminal in your workspace
node "$HolmesCli" runtime-binding status --workspace .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.
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 your workspace
node "$HOLMES_CLI" guidance check --target .Terminal in your workspace
node "$HOLMES_CLI" guidance check --target .Terminal in your workspace
node "$HolmesCli" guidance check --target .Terminal in your workspace
node "$HOLMES_CLI" guidance refresh --target . --dry-runTerminal in your workspace
node "$HOLMES_CLI" guidance refresh --target . --dry-runTerminal in your workspace
node "$HolmesCli" guidance refresh --target . --dry-runExpected result — inspect your actual output
- Current or outdated status is clear; after applying, reload instructions in a new session.
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 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 antigravityAsk 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.
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.
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.
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.