Uninstall BYO

There are three removal scopes. A normal project uninstall disconnects one project while leaving its BYO working data and the shared runtime available. Project purge removes that project’s dedicated BYO data. Global uninstall is the explicit full-computer purge.

Remove BYO from one project

Close Codex or Claude sessions using the project, then run:

cd /path/to/your/firmware-project
byo uninstall

From another directory, provide the project explicitly:

byo uninstall --project /path/to/your/firmware-project

This removes BYO-managed Codex and Claude integration files and blocks and unregisters the project. It preserves:

• the shared BYO runtime used by other projects;
• .firm/ project state;
• .agent-workspace/PLAN.md, .agent-workspace/HANDOFF.md, and specifications;
• .agent-backups/; and
• unrelated content in AGENTS.md, CLAUDE.md, .codex, .claude, and .mcp.json.

Purge BYO from one project

Close Codex or Claude sessions using the project, then run from its root:

byo uninstall --purge

From another directory, provide the project explicitly:

byo uninstall --purge --project /path/to/your/firmware-project

This performs the normal project uninstall and also deletes the dedicated BYO roots created for that project, including .agent-workspace/, .agent-backups/, .firm/, .generated/byo/, and BYO-owned skill directories. It preserves project source and unrelated Codex or Claude files and settings.

Completely remove BYO from the computer

Close active Codex and Claude sessions, then run:

byo uninstall --global

This is the explicit full purge: it preflights every unique registered project, applies project purge to each one, then removes the launcher, installed runtimes, global data, state, configuration, cache, and recorded PATH edits. Do not add --purge, --purge-data, or --yes; those forms are not supported.

Danger

byo uninstall --global permanently removes BYO data, state, configuration, cache, installed runtimes, and the launcher. Board profiles, captured evidence, and other retained information in those roots may be unrecoverable.

The command stops before making project or PATH changes if an MCP runtime lease is active or a registered project cannot be cleaned safely. Its error reports the affected project paths.

Compare the three operations

Operation	Removes	Preserves
byo uninstall	BYO integration for one project	Shared runtime, .firm, plans, handoffs, specs, backups, unrelated client configuration
byo uninstall --purge	One project’s BYO integration and dedicated BYO data	Project source and unrelated agent configuration
byo uninstall --global	Every registered project’s BYO data plus all global BYO content	Unrelated project source and configuration only

Every successful uninstall prints a receipt listing removed, preserved, and reverted items. Add --receipt <path> to write the same evidence as JSON:

byo uninstall --receipt ./byo-project-uninstall.json
byo uninstall --global --receipt ./byo-global-uninstall.json

Downloaded release archives, .sha256 receipts, and install.sh or install.ps1 are ordinary files outside the BYO installation. Uninstall does not delete them automatically.