Guides
Operate: doctor, heal, upgrade#
Installing is one command. Keeping an install correct across host updates, package releases and edited config is the day-two job, and doctor is its single entry point: it tells you whether the install is complete and whether it is current, and every finding names the command that clears it.
1. The day-two loop#
Four verbs cover the whole lifecycle. Each one is idempotent, prints a per-host diff, and works the same under a branded bin (acme-db doctor) or the framework CLI (agent-connector doctor).
| Verb | Question it answers | Exit code |
|---|---|---|
install | Render the connector into every detected host; register it; write the home binary. | non-zero on a write failure |
doctor | Is everything we wrote still there, intact, and rendered by the version now running? | non-zero only on [FAIL]; warns alone exit 0 |
doctor --heal / upgrade | Re-render what drifted. upgrade also refreshes the home binary and prints the npm update line; neither ever self-updates the package. | non-zero if a fixable finding still fails afterwards |
uninstall | Remove every entry, block and file we own; leave user edits alone. | non-zero on a removal failure |
2. Read doctor output#
The first group is always agent-connector: — the framework's own checks. Host groups follow, one per detected host, each check as [pass], [warn] or [FAIL] with a fix: line when there is something to run. --json emits the same groups as an array for scripts.
$ acme-db doctor
agent-connector:
[pass] agent-connector: home-bin — execs /…/node_modules/@ken-jo/agent-connector/dist/cli.js
[pass] agent-connector: home-bin version — 0.6.5
[pass] acme-db: framework version — 0.6.5
[pass] acme-db: connector version — 1.0.0
claude-code:
[pass] Claude Code: config present — /Users/me/.claude.json
[pass] Claude Code: settings.json present — /Users/me/.claude/settings.json
[pass] Claude Code: hook command registered — hook command present
[pass] Claude Code: statusline wired — statusLine command present
doctor: all checks passed.What each framework line proves
home-bin: the stable launcher every host hook and action execs exists and points at a CLI file that exists. A launcher pointing at a removed install is a [FAIL] — hooks, statusline and actions would silently stop on every host. home-bin version: that CLI is the same agent-connector release as the one running doctor. framework version: this connector's host config was rendered by the running release. connector version: the registered connector version equals what the source file declares now.3. Three versions doctor compares#
| Version | Recorded where | Drifts when |
|---|---|---|
| Connector version | connector.json under the framework state dir, at install | you bump version in defineConnector() / package.json and have not re-rendered |
| Framework version | connector.json → frameworkVersion (stamped since 0.6.5) | a newer @ken-jo/agent-connector is installed but hosts still carry the older rendering |
| Home-bin target | the launcher script itself (it execs an absolute dist/cli.js) | the package moved (global reinstall, different Node, removed node_modules) |
$ acme-db doctor
agent-connector:
[pass] agent-connector: home-bin — execs /…/node_modules/@ken-jo/agent-connector/dist/cli.js
[warn] agent-connector: home-bin version — launcher runs agent-connector 0.6.4, this CLI is 0.6.5
fix: run `upgrade` (or `doctor --heal`) to re-render and re-point the home binary
[warn] acme-db: framework version — rendered by agent-connector 0.6.4, running 0.6.5
fix: run `upgrade` (or `doctor --heal`) to re-render acme-db
[warn] acme-db: connector version — registered 0.9.0, source declares 1.0.0
fix: run `upgrade` (or `doctor --heal`) to re-render acme-db
…
doctor: all checks passed. # warns never fail doctor; only [FAIL] does
$ acme-db upgrade
…
Refreshed home binary pointer: /Users/me/.agent-connector/bin/agent-connectorEvery version finding is a [warn] except a launcher whose target file is gone, which is a [FAIL]. All of them are fixable: one upgrade re-renders every host, re-registers the connector with the running versions and re-points the launcher. Records written by releases before 0.6.5 carry no framework version; doctor says so and the same upgrade stamps it.
4. doctor --heal versus upgrade#
doctor --heal is a targeted sync: it re-renders only the connectors that have fixable findings and reports each finding as healed, still failing or deferred. Deferred means agent-connector will not overwrite it — a memory block or config value the user edited by hand stays as the user left it. upgrade is the broad form: re-render everything, refresh the launcher, and print the exact npm i -g line when the install looks npm-managed. Use --dry-run on either to see the plan first.
$ acme-db doctor --heal --dry-run
would heal via sync (acme-db): acme-db: connector version
$ acme-db doctor --heal
healed (1):
[pass] acme-db: connector version
doctor --heal: all fixable findings resolved.5. Prove the live server and the hook matrix#
Placement checks read files. --probe spawns the connector's real stdio server and runs the MCP handshake the hosts will run — initialize, ping, tools/list — so a broken build or a missing runtime dependency shows up here, not in a user's first chat turn. --explain is offline: for every declared hook event it prints whether each targeted host honors the reply, degrades it, or never fires it, so you know which hosts your hook logic can rely on before shipping.
$ acme-db doctor --probe
…
probe acme-db:
[pass] acme-db: MCP initialize — serverInfo [email protected], protocol 2025-11-25
[pass] acme-db: capabilities — tools
[pass] acme-db: ping — alive
[pass] acme-db: tools/list — 2 tool(s)
$ acme-db doctor --explain
acme-db — per-event hook honor:
[honored] claude-code / PreToolUse — claude-code asks on PreToolUse
[degraded] amp / SessionStart — amp drops context on SessionStart (no stdout path)
[dropped] antigravity-cli / SessionStart — antigravity-cli has no SessionStart equivalent — install skip-warns it; never fires6. Reverse it cleanly#
uninstall is the exact inverse of install: every host entry, block and file agent-connector wrote is removed and files it does not own are left untouched. The connector's registry record stays, so a later install is a no-op diff; uninstall --purge removes that record too and, once no connector remains, the home binary. Run doctor afterwards — host groups that no longer mention the connector are the proof.
$ acme-db uninstall
✓ Removed acme-db from 1 host · 4 files cleaned.
Verify it's gone: agent-connector doctor
$ acme-db doctor # host groups no longer list acme-db; the framework rows
# still show its registry record until --purge
$ acme-db uninstall --purge # also drops the record and, when no connector remains, the home binaryNext: ship a UCP commerce MCP with the same loop, or go back to adding connector surfaces.