Overview
Agent OS uses two locations: a base installation in your home directory that holds profiles and scripts, and a project installation in each codebase that holds your standards, specs, and product docs.
Base installation
Located at ~/agent-os/:
~/agent-os/
├── commands/
│ └── agent-os/ # Slash commands copied to projects
│ ├── discover-standards.md
│ ├── index-standards.md
│ ├── inject-standards.md
│ ├── plan-product.md
│ └── shape-spec.md
├── profiles/
│ ├── default/
│ │ └── standards/ # Standards for this profile
│ └── rails/
│ └── standards/
├── scripts/
│ ├── project-install.sh
│ ├── sync-to-profile.sh
│ └── common-functions.sh
└── config.yml # Default profile, inheritance
Project installation
Created in your project directory:
your-project/
├── agent-os/
│ ├── standards/ # Your coding standards
│ │ ├── api/
│ │ │ ├── response-format.md
│ │ │ └── error-handling.md
│ │ ├── database/
│ │ │ └── migrations.md
│ │ └── index.yml # Index for matching
│ ├── specs/ # Saved specs from /shape-spec
│ │ └── 2026-01-15-1430-user-comments/
│ │ ├── plan.md
│ │ ├── shape.md
│ │ ├── standards.md
│ │ ├── references.md
│ │ └── visuals/
│ └── product/ # Product documentation
│ ├── mission.md
│ ├── roadmap.md
│ └── tech-stack.md
└── .claude/
└── commands/
└── agent-os/ # Slash commands
├── discover-standards.md
├── index-standards.md
├── inject-standards.md
├── plan-product.md
└── shape-spec.md
Directory purposes
agent-os/standards/
Your coding standards, organized by domain. Subfolders group related standards. Files at the root level (not in subfolders) are indexed under root.
agent-os/standards/index.yml
Maps standards to descriptions for quick matching. Created and maintained by /discover-standards and /index-standards.
agent-os/specs/
Saved specs from /shape-spec. Each spec gets a timestamped folder with the feature slug.
agent-os/product/
Product documentation created by /plan-product. Used by /shape-spec for context.
.claude/commands/agent-os/
Slash commands for Claude Code. Copied from the base installation during project install.
What to commit
Typically commit:
agent-os/standards/— Share standards with your teamagent-os/product/— Share product contextagent-os/specs/— Preserve project history
The .claude/commands/ folder can be committed or gitignored—team members can regenerate it from their base installation.
Stay updated on Agent OS
Get notified of major new releases and updates to Agent OS.