Repository navigation
Claude Code plugin: let updates reach installs, and add onboarding scripts and guide - #61
Merged
Merged
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
⊙ Problem
Claude Code replaces an installed plugin only when its version changes. Our manifests pinned
0.1.0and never changed, soclaude plugin updatenever 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 tomainreaches installs on the next marketplace refresh plusclaude plugin update, starting with this one. A unit test fails if aversionreturns.docs/onboarding.mdandscripts/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 servesmain, 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
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, thenmarketplace update+plugin update, printed "updated from c85051164abc to a21b1d617968".0.2.0updated 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.5and#<full sha>both pin correctly; the guide's rollback uses that.better-alternative-exists), and the measurements confirmed it. Pinning users to release tags was rejected because every update would need a re-add.🔧 Changes
plugin.jsonand the marketplace entry dropversion; the manifest test is the gate. README › Releasing, the plugin README's Updates section, the CHANGELOG and DESIGN.md › Claude Code plugin › Distribution state the rule that every main commit is a plugin release.scripts/onboarding/, sharingcommon.sh. Both installers read the env file with the plugin's own parser, never a URL or token exported in the shell, and write config files by temp file plus rename.install-claude-profile.shinstalls into, or updates, one profile and setsAGENT_MEMORY_URLin its settings.install-codex.shadds the MCP entry and hooks to a Codex home. It copies the plugin into<codex-home>/agent-memory/plugin, because Claude Code deletes replaced cache directories 14 days after an update. It replaces its own hooks in place, because Codex keys hook trust by position. The hook commands name the env file the MCP credential came from.hook-test.shruns the installed hooks for one synthetic session, with the profile's settings env, and fails unless session start got an answer, and recall got one or is switched offconfigureCodexand the line-based TOML table remover: they rewrite a user's Codex config.docs/onboarding.md, linked from both READMEs.🤔 Codex hooks are marked trusted, and TOML is edited without a parser
As the task asked,
install-codex.shkeeps thetrusted_hashlogic, 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 test548/548 (22 new tests, intest/onboarding.test.jsand the manifest test);npm run format:checkpasses.hook-test.shgaveinjectedon both hooks against the team server (exit 0) andhttp_401with a fake credential (exit 1).More checks
5fdfffed67e7→33891b9b2197→e2c48ac9885b.config.tomlmode 0600. The generated hook command, run throughsh, ignored an exportedAGENT_MEMORY_URLand used the pinned env file./bin/bash3.2.Refs #57
Claude Opus 5.5
🤖 Generated with Claude Code
Related PRs: 2 others independent
Deferred findings
7006397a1dfd9338minor reliability —scripts/onboarding/lib.mjs— runtime gap between renames; recycled-PID cleanup can delete the only old copy — filed Onboarding scripts: known limits to revisit (Codex TOML edits, interrupted installs) #624566432139a6f85eminor data-integrity —scripts/onboarding/lib.mjs— multiline string with a header-like line corrupted; quoted-parent header duplicated — filed Onboarding scripts: known limits to revisit (Codex TOML edits, interrupted installs) #62ec8a8cc844192ca7minor data-integrity —scripts/onboarding/lib.mjs— backup skipped for a header-shaped line inside a multiline string — filed Onboarding scripts: known limits to revisit (Codex TOML edits, interrupted installs) #62dfe147095d6243e4nit maintainability —scripts/onboarding/lib.mjs— new module in JavaScript, not TypeScript — filed Onboarding scripts: known limits to revisit (Codex TOML edits, interrupted installs) #62ae7721502ff829f2nit maintainability —scripts/onboarding/lib.mjs— added comments narrate code or repeat docs — filed Onboarding scripts: known limits to revisit (Codex TOML edits, interrupted installs) #620e1aa06517b23bd5nit reliability —scripts/onboarding/lib.mjs— hooks/trust pair mismatched on kill or a concurrent installer — filed Onboarding scripts: known limits to revisit (Codex TOML edits, interrupted installs) #629fe88103a5a4d2a0nit data-integrity —scripts/onboarding/lib.mjs— line remover deletes adjacent user comments; a nested-array line ends removal early — filed Onboarding scripts: known limits to revisit (Codex TOML edits, interrupted installs) #62Origin — 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
Dispatch: task
agent-memory-plugin-version-and-onboarding· queued by kris-session · ran by claude/opus/high · worker kris-mac-m3-fleet-18b9c6Ready-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