Upgrades and releases
How the upgrade skill reconciles a home after a plugin update, what each version asks of you, and the format maintainers write.
A plugin update replaces files in the plugin's folder. Your home was copied out of templates/ once at setup and has been yours to edit since, so an update cannot safely overwrite it. The upgrade skill reconciles the home separately, on your terms. For the commands, see Updating.
How upgrading works
Knowing the home is behind
The home records its template version in .state/version.json, which is tracked in git and so survives a clone. Comparing it with the installed plugin.json gives three states. No network call is made.
| State | Meaning | What you see |
|---|---|---|
current | The baseline equals the installed version | Nothing |
pending | The baseline is behind; migrations are waiting | An "Upgrade ready" notice, an alert at two or more releases behind, and an amber "upgrade · N" badge on the dashboard |
onboard | No version.json yet | A "Turn on update tracking" notice and an "enable updates" badge |
What upgrade does
.state/updates/<from>-to-<to>/.What it guarantees:
- It always backs up first.
- It never overwrites a whole file, and never deletes a section it does not recognise. In
AGENTS.md,SOUL.mdand the like, new sections are added, changed ones updated, and sections you added kept. - It adds settings entries and never removes yours.
- It applies on its own only what the release marked mandatory or additive.
- Running it twice changes nothing the second time.
- A renamed agent stays renamed: the skill reads the agent's name from your
IDENTITY.mdbefore it compares, so template changes arrive in your agent's name.
Moving from agent-kevin
agentlayer 1.0 replaces the agent-kevin plugin, and a home doesn't upgrade across. It moves: agent-kevin's /agent-kevin:move copies the home to a new folder and changes only the copy, and agentlayer's upgrade finishes the job there.
upgrade. The move skips a home that isn't on the installed version./agent-kevin:move. It lists every agent-kevin home on the machine and asks which to move. For each one it asks the new name and a folder that doesn't exist yet, previews the move, and reviews every renamed line with you. A line where the old name means someone or something else, such as another person, a login still in use, or a document as it was sent, stays as written. You pick the recent sessions the new home offers first, and it saves a move note. Nothing is moved until you run the command it hands you.upgrade (the 1.0.0 notes) and a sync, checks the move's renamed lines with you, and offers the sessions you picked.- Your past sessions: ask for any of them in the new home, by id or by what it worked on, and
find-sessionloads its notes from the brain. Onlyclaude --resumestays behind, since Claude Code keeps transcripts by folder. - Going back: delete the
"movedTo"line from the old home's.state/version.json. - Yours afterwards: point anything that opens the old folder at the new one, such as an Obsidian vault, a terminal workspace, or the "Agent homes:" line in your auto-mode settings.
Notes by version
Newest first. Each note says what upgrade does on its own, what it asks first, and what is yours to do. A release not listed here needs nothing from you. What each release added is in the Changelog.
1.0.9 · Files as paths, and a livelier heartbeat
- On its own: updates
AGENTS.md. To show you a file, the agent puts its absolute path in the reply, which your terminal turns into a link you Cmd-click (Ctrl-click off macOS) to open in your default app. - Yours, if you run a heartbeat: close its tab and start it again with
/heartbeat, so it picks up the new band and the brain refresh. See Proposals.
1.0.8 · The heartbeat follows the home
- On its own: runs
bun installfor the sidebar library's new version. The cmux sidebar picks up the folded PROPOSED section on its next sync or dashboard refresh.
1.0.6 · Proposals
- On its own: runs
bun installfor the sidebar library's new version, and grantsproposal_addin.claude/settings.json. - Yours, if you want proposals: in Claude Code, run
/heartbeatin one session you'll leave open in the home. In cmux, the PROPOSED section's card starts one for you. Without a heartbeat nothing is proposed, and nothing else changes. See Proposals.
1.0.5 · Files open in your own apps
- On its own: updates
AGENTS.md. To show you a file, the agent hands you! openwith its path, so your system's default app opens it. - Yours, if you open notes in Obsidian: dashboard links now open the file itself instead of Obsidian. To keep Obsidian, add
"MARKDOWN_URL": "obsidian://open?path={path}&paneType=tab"to theenvblock of.claude/settings.local.jsonand refresh the dashboard (Opening links).
1.0.3 · Codex on Sol 6.2, and Artifacts off
- On its own: a home wired for Codex whose
.codex/config.tomlsetsmodel = "gpt-6.1-sol"moves togpt-6.2-sol, once. Any other model is left as it is. - On its own: updates
AGENTS.md. The routing table says where a page asked for outside a skill goes, and the home's tree namesextensions/skills/. - On its own: adds
"enableArtifact": falseto.claude/settings.jsonwhen neither settings file sets the key, so Claude Code stops publishing the home's pages to claude.ai (Artifacts off). To keep Artifacts, set it totrue. - Yours, for an agent not named Oppi: it shows Oppi's colors until
IDENTITY.mdhas aColorsline. Ask the agent to show you the color pairs and set yours.upgradenever edits IDENTITY's## Who. - Yours, with the cmux sidebar: run
upgradein every home on the Mac. Until a home has, the sidebar shows "needs its agent updated to show here" for it. - Yours, for an organisation plugin that ships helpdesk rules at
skills/helpdesk/references/org.md: the skill no longer reads that file. Move its text into each home'sextensions/skills/helpdesk.md(Extending a plugin skill).
1.0.2 · The cmux sidebar
- On its own: runs
bun installfor the sidebar's new library. - Yours, if you want it: on macOS with cmux 0.65.2 or later, run
configure-skillsand pick cmux to put this home in the AgentLayer sidebar.
1.0.1 · Codex names
- Yours, only for a home wired for Codex on 1.0.0:
upgradewrites the newagentlayertables but leaves the old ones. In the home's.codex/config.toml, delete[mcp_servers.agent]and[permissions.agent]and setdefault_permissions = "agentlayer", then delete.codex/rules/agent.rules. A home without.codex/has nothing to do.
1.0.0 · agentlayer
The first release as agentlayer. A home reaches it through the move, and this upgrade is the move's last step.
- On its own: runs
bun installat the plugin root, where the package now lives, and asks you to restart before it syncs. - On its own: updates
AGENTS.md. The bundled server isagent, captures go through thecapturetool, and the CLI line namessrc/cli.ts. - Asks first: SOUL's new core truth, "Many arms, one brain". It also offers four concept articles and
.claude/rules/swift.mdwith/agentlayer:command names, which a moved home already has. - Yours, for an agent that took the name Oppi: IDENTITY's Vibe line can end "An octopus at heart: many arms working at once, one brain behind them."
upgradenever edits IDENTITY's## Who.
Before 1.0: agent-kevin's notes
agentlayer 1.0's upgrade runs none of the notes below. They apply only to a home still on agent-kevin, on its way to 0.9.5 and the move. Before 0.7.0 this page holds only the notes for 0.6.0 and 0.5.3 below; every other step is in the plugin's CHANGELOG.md. A home that far back upgrades through 0.7.3 first.
0.9.3 · A stricter manual
- On its own: three rules land in
AGENTS.md. A safety verdict names the input that would break it and how far the check reached. A claim carried in from a plan or an earlier report is re-read at its source. Shell commands are stricter: no<placeholder>in a command to paste, a check never piped throughtailorgrep, and a pass needs a positive count.
0.9.2 · Idle compaction
- On its own: adds
"idleCompaction": falseto.claude/settings.jsonwhen neither settings file sets the key. A value you set yourself is kept. See Idle compaction.
0.9.1 · A newer Bun, and /task
- Before it starts:
upgradestops until Bun meets the version the plugin needs (Install by hand). Runbun upgrade, thenupgradeagain. - On its own: runs
bun install, which drops the old Playwright patch and downloads Chromium again. The install runs from the plugin's server, outside the sandbox, into the version folder you pulled. The new version is recorded only once it succeeds. If it fails,upgradehands you the command and stops, and a re-run finishes. - Asks first (Xcode pack): the new
.claude/rules/xcode.md. Merge by hand if you edited yours. - Yours: a schedule or script outside the home that runs
/doneneeds/task <id> done. - Yours (Xcode pack): re-run
configure-skills→ Xcode. It allowsxcrun xctrace, asks beforexcrun simctl runtime delete, and hands you thexctracesandbox exclusion and the Apple skills export to run. See Xcode.
0.9.0 · Per-agent subscriptions
- Before it starts:
upgradestops until Claude Code meets the version the plugin needs (Claude Code). Runclaude update. - On its own, only where
.claude/settings.local.jsonsetsCLAUDE_CODE_OAUTH_TOKEN: the token moves to.state/secrets/.env.claude.json(owner-only, with anAGENT_SUBSCRIPTIONmarker) and the key leavessettings.local.json, every other setting kept. A different token already in that file stops the move and says so. A home without a token sees none of this. - Asks first, when the home has a subscription: whether to add the
agentcommand to your shell profile (~/.zshrc,~/.bashrcor the PowerShell profile, which live outside the home), to show you the one-line command instead, or to skip. - Yours: from then on, start that agent with
agentfrom its home. After the session ends, runsource ~/.zshrc(PowerShell:. $PROFILE.CurrentUserAllHosts) or open a new terminal so the shell knows the command. See Billing per agent.
0.8.11 · Privacy opt-outs
- On its own: adds the four privacy opt-outs to
envin.claude/settings.jsonwhere neither settings file sets them, and removesCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICfrom the home's settings./design, artifacts and Remote Control come back from the next session. - Yours:
upgradenever writes~/.claude/settings.json. If that file sets the old variable, delete the line, or it still applies to every home on the machine. On a Free, Pro or Max account, turn off Help improve Claude in your Claude account. See Privacy.
0.8.10 · Slack
- On its own: grants the
slackskill and addsreports/slack/to the manual. - Yours, to read Slack: run
configure-skills→ Slack. See Slack.
0.8.9 · The GitHub sweep
Nothing changes until you choose it.
- Asks first (GitHub pack): grant
github_sweepbeside the other GitHub tools. Decline and it asks on first use. - Asks first: the SOUL line that makes "tldr" restart step by step, and the IDENTITY line that says the evening wrap ends on tomorrow's first moves. See Everything waiting on you.
0.8.8 · The attention skill
- On its own: a one-time migration.
- Each
projects/<slug>/focus.htmlbecomesattention.html. An existingattention.htmlwins. - The queue cache moves from
.state/focus/to.state/attention/. - Any
focus_writeorSkill(agent-kevin:focus)rule in either settings file becomes its successor in the same allow, ask or deny list. Both files are read first, so one that doesn't parse stops the run with nothing changed. - The manual's memory-routing row and its
reports/radar/comment name the attention skill.
- Each
- Yours: a schedule or script outside the home that runs
/agent-kevin:focus,/focus where-am-ior/focus triageneeds/agent-kevin:attentionor/attention checkpoint all. See Attention.
From this release on, a renamed tool's permission rule moves the way a retired skill's already did. upgrade and seed import map it to its successor in the same allow, ask or deny list, so a dead grant never comes back and a gate you placed carries over.
0.8.7 · Assigning tickets
- Asks first, where the Helpdesk pack grants
helpdesk_note: granthelpdesk_assignbeside it. Decline and it asks on first use. - Yours, on each SupportCandy site a connection reads: if the site runs a caching plugin, turn off REST API caching (LiteSpeed Cache → Cache → Cache REST API) or exclude
/wp-json/supportcandy/, then purge. A ticket list that answers200to a request with no login is being served from the cache. See Helpdesk pack.
0.8.6 · Pull requests and hand-offs
- On its own: adds
github_pr_createtopermissions.askin every home, so opening a pull request always waits for you. Until the rule is there, the server refuses the tool. A Codex home gets its tool prompts whenupgraderegenerates the wiring. - Asks first (Xcode pack): add
mcp__xcode__DocumentationSearchtopermissions.allow. - Asks first (GitHub pack): grant
github_comment_update. See MCP tools.
0.8.5 · Raising tickets
- On its own: two lines of the manual. Scratch files keep the exact path
mktempprinted, with nothing after the X's. A claim about the machine's current state is checked in the same turn. - Yours, in each queue profile (
projects/<slug>/helpdesk.md): rename## Filing bugsto## Raising, and say where feature requests and tasks go if they shouldn't follow bugs. The skill no longer reads the old heading. See Helpdesk. - Yours (Xcode pack): add the ground rule "Set the run destination after every scheme switch" to
.claude/rules/xcode.md.
0.8.4 · Helpdesk queues and the App Store pack
- On its own: grants the
helpdeskskill, and adds the manual's lines forreports/helpdesk/and a project'shelpdesk.md. Your existing helpdesk keys keep working as the default connection. - Asks first (Helpdesk pack): grant the four new reads,
helpdesk_connections,helpdesk_accounts,helpdesk_lookupsandhelpdesk_stats. Decline and each asks on first use. - Yours, to work a project's queue: run
helpdesk setup acme-shopor say "set up helpdesk for acme-shop". See Helpdesk. - Yours, to read an app's App Store reviews: run
configure-skills→ App Store.
0.8.3 · GitHub writes and a token per owner
Nothing changes until you choose it. Your GITHUB_TOKEN keeps working for every repo.
- Asks first (GitHub pack): grant the four write tools (
github_issue_create,github_issue_comment,github_issue_update,github_pr_update) and denyghin the agent's own shell. A home wired for Codex gets the deny as a forbidden rule. Decline to keep the pack read-only. - Yours, when your repos sit under more than one GitHub owner: add a
GITHUB_TOKEN_<OWNER>=line per owner to.state/secrets/.envin your editor (my-org→GITHUB_TOKEN_MY_ORG) and restart. For writes, give that owner's token Issues or Pull requests: Read and write. See GitHub pack.
0.8.1 · Media and scripts at the home root
.claude/ now holds only what Claude Code itself reads.
- On its own: moves the avatar from
.claude/assets/toassets/, and each browser flow from.claude/browser-flows/<flow>/toscripts/browser/<flow>/with its.env. It then pointsIDENTITY.mdat the moved avatar. Where the new path already holds the same file, the old copy goes. Where it holds a different one, both stay and the report names it. Runningupgradeagain changes nothing. - Yours: in the
## Whoblock ofIDENTITY.md, change theKindline fromAI assistant (Claude Code plugin)toAI assistant (agent CLI plugin).upgradenever edits that block. - Yours: a flow or script of your own that names
.claude/browser-flows/or.claude/assets/by path needs the new path. - Yours: a seed bundle made before 0.8.1 no longer imports. Export it again from an updated home.
0.8.0 · One name per setting
Before 0.8.0 a KEVIN_* variable overrode its AGENT_* twin. The plugin now reads AGENT_* alone, and the first upgrade renames what your home still holds.
| Where | What upgrade renames on its own |
|---|---|
| Settings | env keys in .claude/settings.json and settings.local.json, and $KEVIN_* references in any string there |
| Secrets | Key names in .state/secrets/.env, line by line, keeping values, comments and the file's permissions |
| MCP servers | References and env keys in .mcp.json |
| The old folder's guards | It removes the .kevin/secrets deny rules that the 0.7.0 move left in both settings files, and the .kevin lines in .gitignore. Your own rules that mention .kevin stay, and a home that still has a .kevin/ folder keeps all of them |
- How it runs: where both spellings are set, the
KEVIN_*value wins, since it was the one in use. Every file is read before any is written, so one that doesn't parse stops the run with nothing changed. Each rewritten file is backed up first. The report names keys, never values. - Yours: restart Claude Code (and Codex) afterwards.
- Yours:
upgradelists, but never edits,KEVIN_*keys in your user-level~/.claude/settings.json. Nothing reads them any more. Delete each, and move a per-home value into each home'ssettings.local.jsonasAGENT_*. - A home still on
.kevin/: from 0.8.0 the plugin no longer reads or moves that folder. Run v0.7.3'supgradefirst.
0.7.2 · RunCodeSnippet stops asking, and the theme switch
- On its own (Xcode pack): removes the old ask entry for
mcp__xcode__RunCodeSnippetfrom.claude/settings.jsonand leaves every other entry in place. The test and run tools already run Swift the agent writes, so the prompt removed no capability. See Xcode. - Yours: a roadmap or itinerary built before 0.7.2 keeps its old look, without the Auto / Light / Dark switch, until you ask the
roadmaporitineraryskill to render it again. See Light and dark.
0.7.0 · Moving to .state
Before 0.7.0 the data folder was named after the agent (.kevin/). From 0.7.0 every agent uses .state/, and version.json inside it records which plugin owns the folder.
- On its own, with nothing to answer: the first
upgrademoves the folder, in this order.- Writes
"plugin": "agent-kevin"into.kevin/version.json. - Adds the
.state/secretsdeny rules to.claude/settings.jsonand the.state/rules to.gitignore, before anything lands there. The old rules stay until 0.8.0 removes them. - Renames
.kevin/to.state/in one step, with everything inside it. - Rewrites every
.kevin/path in your machine-local config: a server in.mcp.jsonthat loads.kevin/secrets/.env, and anything you put in.claude/settings.local.jsonyourself, such as an env value, a hook or a permission.
- Writes
- If it stops partway: every file it rewrites is backed up under
.state/updates/first, and runningupgradeagain finishes the move.
Close the other sessions first
Close the agent's other sessions before you run upgrade. A session started on the older plugin stops recognizing the home once the folder moves: its tools refuse and its transcript is not captured.
Two things stop the move without changing anything:
- On Windows, a file inside the folder is open (an editor, a sync client, another session). A folder can't be renamed while one is. Close it and run
upgradeagain. - A
.state/folder already exists that does not record this plugin, such as one you made by hand to hold a key. Move what you put there into.kevin/, move.state/aside, and runupgradeagain.
0.6.0 · Standup and the session radar fold into one skill
The standup and where-am-i skills became playbooks of the focus skill, which is attention since 0.8.8.
- On its own: removes the generated
focus.htmlat the home root, which the dashboard's Today tab replaces. A hand-made file at that path is left in place and named in the report. Project pages are untouched. - On its own: drops the two retired skills' grants from
permissions.allowin.claude/settings.jsonand keeps every other entry in its place. - Yours: nothing for plain asks: "standup is coming up" and "where am I" route on their own. A schedule or script that ran
/agent-kevin:standupor/agent-kevin:where-am-ineeds the playbook instead, todayattention standupandattention checkpoint all. See Attention.
0.5.3 · Roadmaps as data
- On its own: moves every
roadmap.html, in the home and underprojects/<slug>/, to the format that carries its data as JSON. Each page is rewritten beside itself and both versions are rendered. The new one replaces the old only when the rendered page is identical, down to the pixel, and the original hasn't changed meanwhile. Any other page is left exactly as it was, keeps working, and is named in the report. - Yours: a migrated roadmap has no dates until you ask
roadmapto add them; it proposes each one for you to confirm. Until then attention sees only its in-progress items. See The data in the pages.
For maintainers
The release skill
release diffs everything since the last tag and groups it into Added, Changed and Fixed. It works out what homes need by inspecting the diff: dependency changes, touched templates, new skills or tools that need permissions. Then it writes the Upgrade block, bumps the version (and the setup guides' release line, so the installer downloads from the new tag), prepends the CHANGELOG entry, and stages a commit and tag for approval. It never commits or tags on its own, and never pushes.
After the release it offers a docs pass on the site: a plan of every page the release adds, changes or removes, with each line of the CHANGELOG entry mapped to a page, shown for approval. It then writes the pages, regenerates the plugin facts and the demo dashboard, and runs the docs lint. The facts wait for the release tag, since the site's install redirects point at it. Pushing the plugin and the site stays with the maintainer, the plugin first.
The Upgrade-block format
Each release in the plugin's CHANGELOG.md carries an ### Upgrade section. Every actionable line is a backticked tag plus a note:
- `<kind>: <severity>` — <note>| kind | severity | what the upgrade does |
|---|---|---|
deps | required | runs bun install |
settings | mandatory | adds the named permission, hook, or env entries |
file | additive | copies a new file if absent |
template/<f> | mandatory | section-merges, applied automatically |
template/<f> | optional | section-merges, asks first with a diff |
script | required | runs a one-time migration at skills/upgrade/scripts/<version>.ts through the run_upgrade tool, outside the sandbox |
manual | any | a step only you can do; surfaced, never silent |
A code-only release writes one line: None — code-only, no bun install or HOME changes.