AgentLayer▸docs
Reference

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.

StateMeaningWhat you see
currentThe baseline equals the installed versionNothing
pendingThe baseline is behind; migrations are waitingAn "Upgrade ready" notice, an alert at two or more releases behind, and an amber "upgrade · N" badge on the dashboard
onboardNo version.json yetA "Turn on update tracking" notice and an "enable updates" badge

What upgrade does

Preflight. Checks the plugin's registration: a checkout registered under a name its catalog no longer carries, a retired marketplace repo, or a stale Codex registration. Each comes with the exact commands that fix it.
Scope. Reads the Upgrade blocks for every release between your baseline and the installed version, or all of them on a first run. Many versions behind is one pass.
Coalesce. Merges the actions, latest wins. The target is the current template state, not a replay of every edit in between.
Back up. Copies every file it will touch into .state/updates/<from>-to-<to>/.
Apply. Each action the way the Upgrade-block format says. Optional changes ask first, with a diff.
Stamp and sync. Writes the new baseline, then runs sync so the dashboard and knowledge reflect the new state.

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.md and 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.md before 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.

Bring the home current on agent-kevin. Update agent-kevin to 0.9.5 and run its upgrade. The move skips a home that isn't on the installed version.
Run /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.
Exit every session in the old home, and don't sync. Exiting saves each session's last turns, and the move carries everything since the last sync across.
Run the command in your own terminal, then install agentlayer for the new folder only, as the move tells you. The old home is only read, apart from a mark that says where it went: its sessions then open with the new folder, and its sync stops.
Open the new folder. The first session greets you as the agent, runs agentlayer's 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-session loads its notes from the brain. Only claude --resume stays 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 install for 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 install for the sidebar library's new version, and grants proposal_add in .claude/settings.json.
  • Yours, if you want proposals: in Claude Code, run /heartbeat in 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.
  • On its own: updates AGENTS.md. To show you a file, the agent hands you ! open with 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 the env block of .claude/settings.local.json and 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.toml sets model = "gpt-6.1-sol" moves to gpt-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 names extensions/skills/.
  • On its own: adds "enableArtifact": false to .claude/settings.json when 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 to true.
  • Yours, for an agent not named Oppi: it shows Oppi's colors until IDENTITY.md has a Colors line. Ask the agent to show you the color pairs and set yours. upgrade never edits IDENTITY's ## Who.
  • Yours, with the cmux sidebar: run upgrade in 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's extensions/skills/helpdesk.md (Extending a plugin skill).

1.0.2 · The cmux sidebar

  • On its own: runs bun install for the sidebar's new library.
  • Yours, if you want it: on macOS with cmux 0.65.2 or later, run configure-skills and 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: upgrade writes the new agentlayer tables but leaves the old ones. In the home's .codex/config.toml, delete [mcp_servers.agent] and [permissions.agent] and set default_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 install at 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 is agent, captures go through the capture tool, and the CLI line names src/cli.ts.
  • Asks first: SOUL's new core truth, "Many arms, one brain". It also offers four concept articles and .claude/rules/swift.md with /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." upgrade never 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 through tail or grep, and a pass needs a positive count.

0.9.2 · Idle compaction

  • On its own: adds "idleCompaction": false to .claude/settings.json when 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: upgrade stops until Bun meets the version the plugin needs (Install by hand). Run bun upgrade, then upgrade again.
  • 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, upgrade hands 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 /done needs /task <id> done.
  • Yours (Xcode pack): re-run configure-skills → Xcode. It allows xcrun xctrace, asks before xcrun simctl runtime delete, and hands you the xctrace sandbox exclusion and the Apple skills export to run. See Xcode.

0.9.0 · Per-agent subscriptions

  • Before it starts: upgrade stops until Claude Code meets the version the plugin needs (Claude Code). Run claude update.
  • On its own, only where .claude/settings.local.json sets CLAUDE_CODE_OAUTH_TOKEN: the token moves to .state/secrets/.env.claude.json (owner-only, with an AGENT_SUBSCRIPTION marker) and the key leaves settings.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 agent command to your shell profile (~/.zshrc, ~/.bashrc or 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 agent from its home. After the session ends, run source ~/.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 env in .claude/settings.json where neither settings file sets them, and removes CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC from the home's settings. /design, artifacts and Remote Control come back from the next session.
  • Yours: upgrade never 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 slack skill and adds reports/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_sweep beside 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.html becomes attention.html. An existing attention.html wins.
    • The queue cache moves from .state/focus/ to .state/attention/.
    • Any focus_write or Skill(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.
  • Yours: a schedule or script outside the home that runs /agent-kevin:focus, /focus where-am-i or /focus triage needs /agent-kevin:attention or /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: grant helpdesk_assign beside 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 answers 200 to 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_create to permissions.ask in 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 when upgrade regenerates the wiring.
  • Asks first (Xcode pack): add mcp__xcode__DocumentationSearch to permissions.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 mktemp printed, 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 bugs to ## 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 helpdesk skill, and adds the manual's lines for reports/helpdesk/ and a project's helpdesk.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_lookups and helpdesk_stats. Decline and each asks on first use.
  • Yours, to work a project's queue: run helpdesk setup acme-shop or 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 deny gh in 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/.env in 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/ to assets/, and each browser flow from .claude/browser-flows/<flow>/ to scripts/browser/<flow>/ with its .env. It then points IDENTITY.md at 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. Running upgrade again changes nothing.
  • Yours: in the ## Who block of IDENTITY.md, change the Kind line from AI assistant (Claude Code plugin) to AI assistant (agent CLI plugin). upgrade never 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.

WhereWhat upgrade renames on its own
Settingsenv keys in .claude/settings.json and settings.local.json, and $KEVIN_* references in any string there
SecretsKey names in .state/secrets/.env, line by line, keeping values, comments and the file's permissions
MCP serversReferences and env keys in .mcp.json
The old folder's guardsIt 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: upgrade lists, 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's settings.local.json as AGENT_*.
  • A home still on .kevin/: from 0.8.0 the plugin no longer reads or moves that folder. Run v0.7.3's upgrade first.

0.7.2 · RunCodeSnippet stops asking, and the theme switch

  • On its own (Xcode pack): removes the old ask entry for mcp__xcode__RunCodeSnippet from .claude/settings.json and 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 roadmap or itinerary skill 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 upgrade moves the folder, in this order.
    1. Writes "plugin": "agent-kevin" into .kevin/version.json.
    2. Adds the .state/secrets deny rules to .claude/settings.json and the .state/ rules to .gitignore, before anything lands there. The old rules stay until 0.8.0 removes them.
    3. Renames .kevin/ to .state/ in one step, with everything inside it.
    4. Rewrites every .kevin/ path in your machine-local config: a server in .mcp.json that loads .kevin/secrets/.env, and anything you put in .claude/settings.local.json yourself, such as an env value, a hook or a permission.
  • If it stops partway: every file it rewrites is backed up under .state/updates/ first, and running upgrade again 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 upgrade again.
  • 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 run upgrade again.

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.html at 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.allow in .claude/settings.json and 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:standup or /agent-kevin:where-am-i needs the playbook instead, today attention standup and attention checkpoint all. See Attention.

0.5.3 · Roadmaps as data

  • On its own: moves every roadmap.html, in the home and under projects/<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 roadmap to 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>
kindseveritywhat the upgrade does
depsrequiredruns bun install
settingsmandatoryadds the named permission, hook, or env entries
fileadditivecopies a new file if absent
template/<f>mandatorysection-merges, applied automatically
template/<f>optionalsection-merges, asks first with a diff
scriptrequiredruns a one-time migration at skills/upgrade/scripts/<version>.ts through the run_upgrade tool, outside the sandbox
manualanya step only you can do; surfaced, never silent

A code-only release writes one line: None — code-only, no bun install or HOME changes.

On this page