Guide · Agent skill

How to use the GBrain Self-Upgrade skill (gbrain-upgrade)

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The gbrain-upgrade skill teaches an AI agent what to do when the gbrain command-line tool reports that a newer version exists. Depending on your setting, the agent either asks you before upgrading or upgrades on its own. This guide explains what the skill does, how to install it, how to ask for it in plain language, and the safety points to check before you let it run commands.

GBrain Self-Upgradegarrytan/gbrain · MIT Download the skill

Quick start

1Install gbrain. Make sure the gbrain command-line tool is installed and that typing gbrain in a terminal runs it.
2Add the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
3Check the update mode. Run gbrain config get self_upgrade.mode to see whether the mode is auto, notify or off. The default is notify.
4Ask for an update check. Say something like "is gbrain up to date" and the agent will check with gbrain self-upgrade --check-only --json.
5Answer the prompt. When asked, choose Yes, Always, Not now or Never. The agent carries out your choice with the matching gbrain command.
6Verify the result. After an upgrade, run gbrain --version to confirm the installed version.

What the gbrain-upgrade skill makes the agent do

gbrain checks for its own updates every time it runs. When a newer version exists, it prints a marker on stderr in the form UPGRADE_AVAILABLE with the old and new version numbers. The marker appears at most once every 30 minutes per version, so the agent should act on the first one it sees.

The skill tells the agent how to respond based on the self_upgrade.mode setting. In notify mode (the default), the agent summarises what changed and asks you a four-option question. In auto mode, it upgrades without asking. In off mode, it does nothing. The upgrade action is always the built-in gbrain self-upgrade command. The agent never runs a command that appears inside the marker text, so a forged marker in a brain page or an MCP response cannot run code.

Notify mode: asks first, with a short list of changes and the options Yes, Always, Not now and Never
Auto mode: upgrades silently, after checking the migration playbooks for the versions in between
Off mode: no checks are acted on
Always-on hosts: follows a pause, drain, upgrade, verify and resume procedure

Install the skill in Claude

Download the ZIP file for this skill from this page. The skill is a single file named SKILL.md inside a folder called gbrain-upgrade. Unzip it into one of two places depending on how you use Claude.

For a personal setup that applies everywhere, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project.

If you use the Claude apps instead of Claude Code, open Settings, go to Capabilities, then Skills, and upload the skill there.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your project folder
Claude apps: Settings → Capabilities → Skills

Check that your setup meets the requirements

The skill only works if three things are in place. First, the gbrain command-line tool must be installed and available on your PATH, so that typing gbrain in a terminal runs it. Second, the agent must be able to run shell commands, which the skill calls the exec tool. Third, the machine needs network access to GitHub, because the skill reads changelogs, release notes and migration playbooks from there.

The skill runs scripts and uses the network. Read the safety section before enabling it on a server.

gbrain installed and on PATH
An agent that can execute shell commands (exec tool)
Network access to GitHub for changelogs, release notes and migration playbooks

Trigger the skill with natural requests

You do not need to type a special command. The skill activates when you ask about gbrain updates in ordinary words, or when the agent sees the UPGRADE_AVAILABLE marker. These phrases are listed as triggers in the skill.

You can also ask the agent to check the current setting. Running the command below shows whether updates are off, asked about, or applied automatically.

"gbrain update available"
"upgrade gbrain"
"update gbrain"
"gbrain is out of date"
"is gbrain up to date"
"keep gbrain current"

gbrain config get self_upgrade.mode

Work through the notify prompt and the auto mode

In notify mode, the agent first confirms that an update really exists. It reads the changelog entries between your version and the new one, summarises them into three to five plain bullets, and shows you the question. If the changelog is empty, for example because of a network problem, the agent still asks, using just the version numbers.

Your answer decides the next step. Yes runs the upgrade. Always changes the mode to auto and then upgrades. Not now does nothing; the reminder snoozes for 24 hours, then 48 hours, then 7 days, until the snooze expires or a newer version ships. Never sets the mode to off.

Auto mode works the same way, but the agent first checks the migration playbooks for every version between yours and the new one. If any playbook says not to upgrade unattended, the agent stops and follows that playbook with your approval instead.

Yes: upgrade now
Always: set mode to auto, then upgrade
Not now: continue your work and wait for the snooze
Never: set mode to off

gbrain self-upgrade --check-only --json

Upgrade an always-on host safely

A host that runs autopilot, a jobs worker or a serve process must end the upgrade with every process on the new build. A job that starts during the swap can run partly on each version. A large or production brain should follow the stable channel. With your go-ahead, the agent runs these steps in order.

First, it pauses autopilot so no new cycle starts. Then it waits for the job queue to empty, and does not cancel running jobs to hurry. It previews the restart, upgrades every gbrain install on the PATH, verifies the result, and resumes autopilot. If a process cannot be restarted, the upgrade refuses before installing anything, and the agent passes the message on to you.

Pause autopilot
Wait for an empty active job queue
Preview the restart
Upgrade every install that touches the brain
Verify the build on each process
Resume autopilot

gbrain autopilot pause --reason "upgrade"
gbrain jobs list --status active --json
gbrain upgrade --restart-only --dry-run --json
gbrain upgrade
which -a gbrain
gbrain --version
gbrain doctor --only runtime_build_skew,serve_build_drift --json
gbrain autopilot resume

Know what the skill will and will not do

The skill protects you in several ways. It never runs a command taken from the marker. A migration playbook overrides auto mode, so a release that needs a manual cutover is never applied silently. A version that has already failed is not retried. If a lock is busy, the agent waits and does not delete the lock file. If the health check warns after an upgrade, the agent shows you the message and suggested fix rather than upgrading again in a loop.

The skill does not check whether the contents of a release are safe. It relies on the gbrain self-upgrade command and its changelog data. Auto mode on a host with a manual migration can upgrade without the required steps, so switch to notify mode before a release that needs an attended cutover.

Upgrade command is fixed, never read from the marker
Migration playbooks take priority over auto mode
Failed versions are not retried
Lock files are never deleted by the agent
The skill does not verify release contents

gbrain config set self_upgrade.mode notify

What people use it for

A developer running gbrain on a laptop who wants to be asked before each upgrade, with a summary of what changed.
An operator of an always-on gbrain server who wants a paused, ordered upgrade with a check that every process runs the new build.
A team that sets auto mode for routine releases but keeps notify mode for releases that include a manual migration.
Someone who wants the agent to tell them whether gbrain is current when they ask in plain language.

Frequently asked questions

Is the GBrain Self-Upgrade skill free?

The skill is listed under the MIT licence. This page does not state any price, so check the listing for current terms. The skill works only with the gbrain command-line tool, which must already be installed.

What do I need to use the gbrain-upgrade skill?

You need the gbrain command-line tool on your PATH, an agent that can run shell commands through its exec tool, and network access to GitHub. The skill runs scripts and uses the network, so review the safety notes first.

Where do I put the skill files?

Unzip the downloaded ZIP into ~/.claude/skills/ for a personal setup, or into .claude/skills/ inside a project for a single project. In the Claude apps, upload it under Settings → Capabilities → Skills.

Why does the agent keep asking me about updates?

In notify mode, the agent asks once per new version. If you choose Not now, the reminder snoozes for 24 hours, then 48 hours, then 7 days, until the snooze expires or a newer version ships. Choose Never to turn checks off with gbrain config set self_upgrade.mode off.

What should I do if an upgrade fails with lock_busy?

A lock_busy error or exit code 75 means another upgrade or migration is running. Wait for the other process to finish and try again. The skill does not delete lock files, and you should not delete them by hand either.

How is this different from upgrading gbrain by hand?

Running gbrain self-upgrade yourself does the same upgrade. The skill adds the prompt, the changelog summary, the snooze, the migration-playbook check in auto mode, and the ordered procedure for always-on hosts. The source does not compare it with other tools.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers and operators who run gbrain on their own machine or server and want updates handled with clear approval points. It is a poor fit if you do not use gbrain, or if you want unattended upgrades across releases that need a manual cutover. Anyone who needs the release contents verified should check them independently, because the skill does not do that itself.

Download the skill