Installation Guide

Agent OS uses a two-step installation: first install the base system to your home directory, then compile it into individual projects.

1Base installation

Run the base installation script to install Agent OS to your home directory:

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

This creates ~/agent-os with the default profile containing standards, workflows, agents, and installation scripts.

Alternatively: You can manually download the files from the GitHub repository and place them in your home directory at ~/agent-os/.

Updating? If you already have Agent OS installed, you’ll be prompted with update options and the ability to create a backup. For more information on updating, see the updating guide.

Windows Users: The installation command requires a bash shell. We recommend using Windows Subsystem for Linux (WSL), which provides a full Linux environment on Windows. Alternatively, you can use Git Bash (included with Git for Windows) to run the installation command. Once installed, open your bash terminal and run the curl command above.

Customize your standards

Before installing Agent OS into your projects, take time to customize your coding standards. This is one of the most important steps—your standards define how agents understand and build your code.

Best practice: Create a custom profile that inherits from the default profile rather than editing the default profile directly. This makes updating your base installation easier without losing your customizations. Edit the files in your custom profile’s standards/ folder to match your conventions, preferred frameworks, and architectural patterns.

Learn more about standards

For Claude Code users with Skills enabled

If you’re using Claude Code Skills integration (enabled by default when standards_as_claude_code_skills: true), run the /improve-skills command after customizing your standards or after installing Agent OS into a project.

This command analyzes each Skill and optimizes its description to improve how Claude recognizes when to apply it, ensuring your standards get used effectively throughout your development workflow.

2Project installation

Navigate to your project:

cd /path/to/your/project

Install Agent OS:

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

The installer will use your defaults from ~/agent-os/config.yml or prompt you for:

• Which profile to use (default: default)
• Your configuration options for Claude Code commands, subagents, and standards

What gets installed

The project installation compiles from your base:

• standards from your chosen profile
• commands adapted for your configuration options
• workflows configured for your project

This creates:

• agent-os/ folder with standards and workflows
• .claude/ folder with commands (only when claude_code_commands: true)

Configuration defaults

Set defaults in ~/agent-os/config.yml:

defaults:
  profile: default
  claude_code_commands: true
  use_claude_code_subagents: true
  agent_os_commands: false
  standards_as_claude_code_skills: true

Installation options

Override defaults using flags:

Example flag usage

Use a different profile:

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

Enable Claude Code with subagents:

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

Enable Claude Code without subagents:

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

Enable for other AI coding tools:

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

Enable Claude Code Skills:

~/agent-os/scripts/project-install.sh --claude-code-commands true --standards-as-claude-code-skills true

Preview installation without running it:

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