Updating Agent OS

This page documents how to update Agent OS including:

• Upgrading your base installation to the newest version of Agent OS
• Pushing updates to your project repositories

For notes on the latest version of Agent OS, see the changelog.

Note: If you're upgrading from Agent OS 1.x to 2.x, see the Version 2 Migration Guide.

Updating your base installation

Your base installation in ~/agent-os is the source where your project installations will be compiled from. Update your base installation so that you have the latest version of Agent OS available on your system.

Note: Updating your base installation will not automatically update your project installations. You will need to update your project installations separately by following these instructions below.

Running the base installation update

curl -sSL "https://raw.githubusercontent.com/buildermethods/agent-os/main/scripts/base-install.sh" | bash

Choosing your update option

When you run the update script, you'll be presented with several update options. For most users, option 1 (Full update) is recommended as it updates your base installation to the latest version while preserving your important customizations.

1. Full update (Recommended)
2. Update default profile only
3. Update scripts only
4. Update config.yml only
5. Delete & reinstall fresh

1. Full update (Recommended)

What it does:

• Updates and overwrites the default profile (~/agent-os/profiles/default/*)
• Updates and overwrites all core scripts (~/agent-os/scripts/*)
• Updates only the version number in config.yml
• Updates CHANGELOG.md

What's preserved:

• Your config.yml file's contents and settings remain completely intact (only the version number is updated)
• All custom profiles you've created remain completely intact

When to use it: This is the standard update path. Choose this option to get the latest Agent OS features while keeping your customizations safe.

2. Update default profile only

What it does: Updates and overwrites only the files in ~/agent-os/profiles/default/*. Everything else in your ~/agent-os folder remains completely unchanged.

When to use it: Choose this if you specifically want to refresh just the default profile without updating scripts or other components.

3. Update scripts only

What it does: Updates and overwrites only the files in ~/agent-os/scripts/*. Everything else remains unchanged.

When to use it: Choose this if you need to update just the installation and compilation scripts, perhaps to get a bug fix in the scripts without affecting your profiles.

4. Update config.yml only

What it does: Updates and overwrites only the ~/agent-os/config.yml file. Everything else remains unchanged.

When to use it: Choose this in rare cases where you need to update just the configuration file structure.

5. Delete & reinstall fresh

What it does:

• Creates a backup of your entire ~/agent-os folder at ~/agent-os.backup
• Deletes your existing ~/agent-os folder and all of its contents
• Installs a completely fresh Agent OS base installation

When to use it: Choose this if you want to start completely fresh or if you're experiencing issues with your current installation. You can restore any customizations from the backup afterward.

Updating your project installations

After you've updated your base installation, or after you've made changes to your base installation, you can push those updates to individual project installations. The update process has been simplified in Agent OS 2.1 to make it easier and more predictable.

Running a project update

Navigate to the root of your project directory:

cd /path/to/your/project

You can use either the explicit project update script:

~/agent-os/scripts/project-update.sh

Or re-run the installation script (it will automatically detect and update existing installations):

~/agent-os/scripts/project-install.sh

How the update process works

When you run a project update, the script will:

1. Check your current Agent OS configuration
2. Compare it with the incoming Agent OS version and configuration
3. Show you what will change and ask you to confirm before proceeding
4. Preserve your important project data (specs and product docs)
5. Delete and re-install everything else from your base installation

What gets preserved

The following folders are always preserved during updates and never deleted:

• agent-os/product/* - Your product roadmap, mission, and tech stack
• agent-os/specs/* - All your feature specs and implementations

What gets re-installed

The following are completely deleted and re-installed from your base installation (using your selected profile and configuration options):

• agent-os/standards - All standards from your profile
• agent-os/commands - If agent_os_commands: true
• .claude/commands/agent-os/ - If claude_code_commands: true
• .claude/agents/agent-os/ - If using Claude Code with use_claude_code_subagents: true
• .claude/skills - If using Claude Code Skills with standards_as_claude_code_skills: true

Common update scenarios

curl -sSL "https://raw.githubusercontent.com/buildermethods/agent-os/main/scripts/base-install.sh" | bash

cd /path/to/your/project
~/agent-os/scripts/project-update.sh

~/agent-os/scripts/project-install.sh --profile your-new-profile

~/agent-os/scripts/project-install.sh --claude-code-commands true --use-claude-code-subagents true

~/agent-os/scripts/project-install.sh --claude-code-commands true --use-claude-code-subagents false

~/agent-os/scripts/project-install.sh --agent-os-commands true

/improve-skills