Skip to content

Claude Code plugin: let updates reach installs, and add onboarding scripts and guide - #61

Merged
kriszyp merged 7 commits into
mainfrom
claude-plugin-updates-and-onboarding
Nov 21, 2026
Merged

kriszyp merged 7 commits into
mainfrom
claude-plugin-updates-and-onboarding

Conversation

@kriszyp

@kriszyp kriszyp commented Nov 20, 2026 •

Copy link
Copy Markdown
Member
The daughter pries an old 0.1.0 plate off the relay gate stamp post so fresh crates reach the camps, while the son hands a newcomer a trail guide.

⊙ Problem

Claude Code replaces an installed plugin only when its version changes. Our manifests pinned 0.1.0 and never changed, so claude plugin update never replaced an install: no plugin fix since, #50 and #57 included, reached anyone. There was also no written path from a new user to a working install.

💡 Solution

The manifests now carry no version, so Claude Code versions the plugin by commit: every merge to main reaches installs on the next marketplace refresh plus claude plugin update, starting with this one. A unit test fails if a version returns. docs/onboarding.md and scripts/onboarding/ take an engineer from a provisioned user through install, verify, update and rollback.

⚖️ Alternatives

🤔 No version at all, rather than a version kept in step with package.json

The task suggested lockstep with package.json, but the marketplace serves main, so fresh installs would get unreleased code under a released number. A bump check races: two PRs can take the same number. Measured on Claude Code 2.1.329: with no version, every commit updated installs. Cost: server-only merges also trigger an identical update.

Measurements and other options
  • In a scratch git marketplace, a versionless plugin installed as cache/<mkt>/<plugin>/<12-char HEAD sha>/. The SHA is the marketplace HEAD, not the last commit touching the plugin directory. A commit changing only a file outside the plugin directory, then marketplace update + plugin update, printed "updated from c85051164abc to a21b1d617968".
  • Moving to an explicit 0.2.0 updated once. A plugin change without a bump then stayed at "already at the latest version (0.2.0)".
  • marketplace add HarperFast/agent-memory#v0.1.5 and #<full sha> both pin correctly; the guide's rollback uses that.
  • The planning review proposed exactly this design (verdict better-alternative-exists), and the measurements confirmed it. Pinning users to release tags was rejected because every update would need a re-add.

🔧 Changes

🤔 Codex hooks are marked trusted, and TOML is edited without a parser

As the task asked, install-codex.sh keeps the trusted_hash logic, so Codex runs the hooks without a review prompt; reviewers preferred approval in /hooks. TOML edits are line-based, with no parser dependency: a header-shaped line inside a multi-line string is taken for a header, and a quoted parent key (["mcp_servers".agent-memory]) is missed.

✅ Verification

  • npm test 548/548 (22 new tests, in test/onboarding.test.js and the manifest test); npm run format:check passes.
  • Real Claude Code 2.1.329 against this checkout: install, then updates across three commits; hook-test.sh gave injected on both hooks against the team server (exit 0) and http_401 with a fake credential (exit 1).
  • Cross-model pre-push review converged after six rounds; the deferred minors below are the 🤔 limits.
  • Docs: in-repo only; the documentation site does not cover this plugin. PR QA: not applicable (not harper or harper-pro).
More checks
  • Updates moved the scratch install 5fdfffed67e7 → 33891b9b2197 → e2c48ac9885b.
  • Codex install run twice on a scratch home: idempotent, config.toml mode 0600. The generated hook command, run through sh, ignored an exported AGENT_MEMORY_URL and used the pinned env file.
  • All scripts run under macOS /bin/bash 3.2.

Refs #57

Claude Opus 5.5

🤖 Generated with Claude Code

Related PRs: 2 others independent

Deferred findings

Origin — the dispatch brief this PR was written from

Make Claude plugin updates reach installs, and add team onboarding (install scripts + doc)

Prepare the Claude Code plugin for a team-wide rollout. Two parts, one PR.

PART 1 — plugin updates must reach installed copies. claude-plugin/.claude-plugin/plugin.json and the plugin entry in .claude-plugin/marketplace.json both say version 0.1.0 and have never changed, while package.json is 0.2.0. Claude Code caches an installed plugin by version (plugins/cache/agent-memory/agent-memory/0.1.0/), so merged plugin fixes such as #57 (recall miss log, short-prompt skip) never reach any install: every profile on the fleet still runs the 0.1.0 code from before #57. Make every plugin change that reaches users carry a new version, and enforce it with a CI gate so it can't silently regress.

PART 2 — onboarding. Move the three install/test scripts below into the repo (suggested: claude-plugin/scripts/ or scripts/), cleaned up for general use, and write an onboarding doc (link it from README.md and claude-plugin/README.md) that takes an engineer from nothing to a working install: (1) an admin provisions their user with deploy/engineering/provision-user.sh at the right role (eng for the person, eng-agents with --acts-for for their agents), which writes ~/.config/agent-memory/env; (2) install into each Claude profile (install-profile script); (3) optionally Codex (install-codex script); (4) verify with the hook-test script; (5) how to update and how to roll back/uninstall.

Acceptance

  • plugin.json, marketplace.json versions are produced by a checked mechanism; CI fails on drift or a missing bump per the chosen approach; tests pass.
  • This PR itself bumps the plugin version so Claude Code plugin: record why prompt-time recall injected nothing, and skip prompts with no topic #57's code reaches installs.
  • Scripts live in the repo with usage headers; the onboarding doc covers provision → install (Claude, Codex) → verify → update → uninstall, and is linked from both READMEs.
  • No hostnames, URLs, user names or secrets in any committed file.
  • Don't change server code or the hook's runtime behavior.

Dispatch: task agent-memory-plugin-version-and-onboarding · queued by kris-session · ran by claude/opus/high · worker kris-mac-m3-fleet-18b9c6

Ready-For-Promotion: d7ed074 urgency=normal late=none

Review-Coverage: authored=claude; ran=codex,gemini; adjudicated=domain; declined=cursor-grok,cursor-composer,muse; rounds=6; full=1 @ d7ed074

Review-Attention: read ~7m (decisions: version-by-commit, codex-inline-secret, codex-auto-approve, line-based-toml-editing, codex-precomputed-trust, do-less-alternative, requirement-shift) @ d7ed074

kriszyp and others added 7 commits November 20, 2026 08:37
…ripts and guide

The plugin's manifests pinned version 0.1.0, so `claude plugin update` never replaced an installed copy and
no plugin fix since 0.1.0 (#50, #57) reached anyone. Both manifests now carry no version: Claude Code then
versions the plugin by the marketplace's commit, so every commit to main is a plugin release. A unit test
fails if either manifest gains a version again.

scripts/onboarding/ holds install-claude-profile.sh, install-codex.sh and hook-test.sh, and
docs/onboarding.md walks from provisioning a user to install, verify, update, rollback and uninstall.

Dispatch-Task: agent-memory-plugin-version-and-onboarding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ook probe honest

- The MCP block rewrite no longer eats [mcp_servers.agent-memory-<x>] and also drops a quoted-key block.
- An earlier agent-memory hook is replaced where it stands, so other hooks keep the positions their Codex trust
  is keyed to; hooks.json is written before the trust records that refer to it.
- Hook commands are shell-quoted, use an absolute Codex home, and carry AGENT_MEMORY_ENV_FILE when it was used.
- No backup is taken of a file that already holds agent-memory entries (it would save the token as the original).
- A failed runtime swap puts the previous copy back.
- hook-test gives the hooks the profile's settings.json env, and fails on a skipped recall or a failed process.
- install-claude-profile checks credentials before needing claude, matches the marketplace by exact name, and
  nvm.sh is sourced outside set -u.

Dispatch-Task: agent-memory-plugin-version-and-onboarding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… credential-source gaps

- MCP block edits match only header lines (any key quoting, indented or not), so a commented example no longer
  deletes settings or suppresses the backup.
- Codex hooks drop inherited AGENT_MEMORY_URL/TOKEN exports, so they use the same env file as the MCP entry.
- A rerun without AGENT_MEMORY_ENV_FILE removes one left in settings.json by an earlier install.
- hooks.json is restored if the config.toml write fails; stale swap directories are cleared first.
- An unreadable marketplace listing stops install-claude-profile instead of reading as "absent".
- The probe reports an injection with no hook output as bad_output; tests cover the answered path.

Dispatch-Task: agent-memory-plugin-version-and-onboarding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ighten the probe

- Codex hook commands name the env file the MCP credential came from, the default included.
- Replacing a trust record no longer takes an indented table that follows it.
- Fallback tool directories go after PATH, so they never shadow an nvm node already found.
- The probe accepts hook output only when it names the expected event with string context.
- A failed runtime copy leaves no staging directory behind.

Dispatch-Task: agent-memory-plugin-version-and-onboarding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…arseable hook output

One line-based table remover replaces both regexes: a header quoted in a comment never matches, and a
removed table takes its blank lines with it without eating the next table. The probe reports bad_output
whenever the hook's stdout is not the expected JSON. The guide says to rerun install-codex.sh after a
password rotation.

Dispatch-Task: agent-memory-plugin-version-and-onboarding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Only text after the header can be a comment; stripping from the first # cut into a Codex home path that has
one, so a rerun added a duplicate trust table.

Dispatch-Task: agent-memory-plugin-version-and-onboarding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…hat install-codex copies

Dispatch-Task: agent-memory-plugin-version-and-onboarding
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kriszyp
kriszyp marked this pull request as ready for review November 21, 2026 05:52
@kriszyp
kriszyp merged commit b1cb81c into main Nov 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant