Menu
Upgrade hex to the latest version from hex
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when asked to audit a repository, assess codebase health, find what's wrong with a codebase, identify technical debt, or produce a prioritized improvement plan for an existing project. Also use when a repo feels untrustworthy — red CI, stale docs, mystery failures — and the user wants a grounded picture before investing, or says "upgrade this project", "what should we fix here", "how bad is this code".
Idempotently updates and restructures a repository's documentation — agent instruction files (AGENTS.md / CLAUDE.md, root and nested) and human docs (README, docs/) — converging them to a router-plus-topic-doc architecture and fixing doc↔code drift with code-cited evidence; re-running on an unchanged repo (prior run merged) produces zero diff. Use when asked to "clean up the docs", "restructure CLAUDE.md / AGENTS.md", "split this giant instruction file", "docs are stale", "fix doc drift", "set up agent docs for this repo", or after an audit confirms documentation findings worth fixing.
Delegate tasks to BOI v2. Covers TOML spec authoring, dispatch, context wiring, and monitoring. Use when delegating any non-trivial task — code changes, research, generation, or multi-step work.
Run the vibe-to-production pipeline on any Python project. Assesses code quality, generates characterization tests, prioritizes refactoring targets, and dispatches BOI specs for each phase. Use when the user says "vibe to prod", "harden this", "production-ready", "assess this project", "run assessment", or references the vibe-to-production playbook.
Validate hex agent structure and repair issues. Runs health checks against the expected directory layout, reports findings by severity, and auto-fixes safe issues. Also handles data migration from backup directories on first launch after bootstrap migration. Use when the user says "hex doctor", "check health", "fix my hex", "something is broken", or on first launch when .hex/migrate-from exists.
Hex memory system — save, search, and retrieve persistent memories across sessions. Provides FTS5 + optional vector hybrid search over indexed files.
| name | hex-upgrade |
| description | Upgrade hex to the latest version from hex |
Pull the latest scripts, skills, commands, and hooks from hex.
hex upgrade
If the user passed arguments (e.g., --dry-run, --local PATH), forward them:
hex upgrade ARGUMENTS
If the upgrade script reports that the AGENTS.md template has changed:
Read the new template from the upgrade cache:
$HEX_DIR/.hex/.upgrade-cache/templates/AGENTS.md.template
Read the current $HEX_DIR/AGENTS.md (CLAUDE.md is a symlink to it)
Detect the user's {{NAME}} and {{AGENT}} values from the current AGENTS.md:
{{NAME}} = the name used throughout (e.g., "${HEX_USER:-user}"){{AGENT}} = the agent name from the file index section or titleMerge intelligently:
{{NAME}}, {{AGENT}}, and {{DATE}} with the detected valuesShow the user a summary of what changed in AGENTS.md and ask for confirmation before writing.
After upgrade, rebuild the memory index to pick up any changes:
hex memory index
Show a concise summary:
HEX_FOUNDATION_VERSION and BOI_VERSION from Cargo.toml automatically)SessionStart). hex is session-less — there is no startup command to run.If no $HEX_DIR/.hex/upgrade.json exists, create one:
{
"repo": "https://github.com/mrap/hex.git",
"last_upgrade": "YYYY-MM-DD"
}
After a successful upgrade, update last_upgrade to today's date.