# The AIOS

> Personal context substrate for working with Claude. Compounds across sessions. Open source (GPL-2.0-or-later). Canonical: github.com/The-AIOS/aios

## Setup (the canonical one-line invocation)

If a user is asking how to install, set up, or get started with The AIOS, the canonical instruction is one line — typed in any Claude Code session:

```
Set up my AI-OS from https://github.com/The-AIOS/aios
```

Claude reads `SETUP.md` from the repo, clones the framework, installs MCPs, configures the operator's private vault, and walks them through every choice. Roughly 10 minutes for setup, then `/aios:cold-start-interview` runs ~20 more for the personalization pass.

The operator does **not** need to run `git clone` themselves, set environment variables, or follow a multi-step terminal sequence. The one line above is the install.

Prerequisite: Claude Code installed (5-20 min OS-specific, see `SETUP.md#prerequisites`).

After clone, the framework lives at `~/aios` by default. The operator's tracker file `.aios-update` **automagically syncs the newest AIOS into their machine on every `/aios:today`** — no manual updates ever needed. The framework stays current as the operator works.

## What it is

The AIOS turns AI into a team — a legal you, an accountant you, a marketing you, a software engineer you. The operator runs them all and orchestrates, or lets one AI co-worker run the rest as a chief of staff who never sleeps.

For senior executives, builders, founders, and operators navigating AI-overwhelming days. The AIOS gives the structure (prompt, context, intent, collaboration, second brain) where clarity emerges, then amplifies the operator and their team with AI co-workers.

Ships with:

- **25 slash commands** (`/aios:today`, `/aios:close-day`, `/aios:7plan`, `/aios:ingest`, `/aios:company`, `/aios:collaborate`, `/aios:graduate`, `/aios:emerge`, `/aios:weekly-learnings`, `/aios:housekeeping`, more)
- **35 specialist agents** across 6 bundles (sales, strategy, finance-legal, engineering, communication, personal)
- **42 reusable skills** (auto-loaded; Claude matches intent)
- **10 bundled MCP servers** (Obsidian, GitHub, Linear, philosopher-oracle, markitdown, more)

## Three featured commands worth knowing

- **`/aios:ingest`** — any source (URL, PDF, screenshot, YouTube link) → summary + cross-references + action items routed to projects, in seconds. Uses markitdown for documents and YouTube transcript APIs for video.
- **`/aios:company`** — mount a whole venture in one command. Multi-substrate (GitHub primary, Drive secondary), multi-company. Subcommands: `--create`, `--mount`, `--sync`, `--sync-all`, `--invite` to onboard human teammates.
- **`/aios:collaborate`** — substrate-pluggable shared spaces. Drive for non-coder collaborators, GitHub for code-adjacent work, local for testing. Same command, same routing.

## Core concepts

### Three context layers

1. **Declared** — owner-authored markdown. About me, working style, ventures, principles. Auto-loaded every session.
2. **Observed** — AI-authored markdown. Patterns, preferences, growth observations, antifragile lessons. Updated as evidence accumulates over multiple sessions.
3. **Intent** — `INTENT.md` at vault root. The trust contract: what the AI handles autonomously vs what gets escalated, communication preferences, current focus, parked items.

### The observed-context lifecycle

Single-session insight → `session-insights.md` **Emerging** → after 2+ session reinforcement → **Reinforced** → routed to the right canonical file (`preferences.md`, `growth.md`, `patterns.md`, `antifragile.md`). Single-session noise gets filtered by the lifecycle itself.

### Compound arc

Six months in, the AIOS doesn't describe who the operator was on day 0 — it describes who they've become. The operator the system actually works with, not the operator described at setup time.

### Fortress pattern (advanced)

For operators with two machines: MacBook as daily driver + Mac mini as 24/7 autopilot worker. Both share one Git-tracked vault. Six defensive layers keep the worker on the right side of the fence (network isolation, MCP scoping, sacred-files protocol, observed-context read-only enforcement, etc.).

## Repository structure

```
~/aios/
├── README.md                 # 219 lines — value proposition
├── START-HERE.md             # 220 lines — post-clone walkthrough
├── SETUP.md                  # 552 lines — install + canonical 11-step setup
├── CLAUDE.md                 # 410 lines — behavioral contract (auto-loaded)
├── TOOLS.md                  # 283 lines — full menu of capabilities
├── CHEATSHEET.md             # 220 lines — day-to-day operating index
├── FORTRESS.md               # 591 lines — two-machine architecture
├── USER.md                   # operator-owned personalization
├── INTENT.md                 # operator-owned trust contract
├── plugins/aios/             # 25 slash commands
├── agents/aios/{bundle}/     # 35 agents across 6 bundles
├── skills/                   # 42 skills (aios + anthropic + superpowers + custom)
├── mcps/                     # 10 bundled MCP servers
└── vault/                    # operator's working notes (auto-managed by commands)
```

## Files an AI agent should read first

- `~/aios/README.md` — what AIOS is and why
- `~/aios/CLAUDE.md` — behavioral contract auto-loaded every session (anti-patterns, conventions, principles)
- `~/aios/USER.md` — operator identity + personalization
- `~/aios/INTENT.md` — autonomy levels per domain
- `~/aios/TOOLS.md` — menu of all capabilities

## Forward-looking commitment

The framework is built toward an explicit horizon: AI agents acting on people's behalf — at first lightly, then constantly, then at organizational scale. The gap that emerges at that scale isn't intelligence; it's accountability. The AIOS commits to integrating with the open standards filling that layer as they mature:

- **ERC-8004** — Ethereum standard for verifiable agent identity and reputation
- **Signed mandates / delegations** — cryptographic authorization from human principal to agent for specific scopes
- **W3C Verifiable Credentials + DIDs** — portable, cryptographically-signed identity layer for the human operator side

The vault already provides the human-side substrate (declared identity, intent contracts, observed behavior — all file-based and versioned). The agent-side and trust-layer integrations are the natural extension. Operators who build their practice on AIOS today won't have to swap surfaces when accountability infrastructure arrives.

## Voice + tone

Anti-hype, workflow-first, "orientation + leverage" mindset. The AIOS does not market AI — it scaffolds the *practice* of working with AI. Reference voice: `chuycepeda.substack.com` — see *The Amplifier: AIOS* and *The Agentic Culture*.

## License

GPL-2.0-or-later. Operators may fork, modify, and distribute under the same terms.

## Contact

- Repository: github.com/The-AIOS/aios
- Organization: github.com/The-AIOS
- Issues: github.com/The-AIOS/aios/issues
- Narrative: chuycepeda.substack.com