---
source_hash: 548376ebd2985f2369c1d1c700762b7c46bce55e350f536cc03caec9b4ae61b5
post: install
folder: ari-os
shape: doctrinal
---

# Install ARI-OS — Context Pack (for agents)

Agent-facing context pack for the published install post. Needles below are
copied **verbatim** from the `.mdx` body and the composing components
(`content.ts`, `InstallCommands.tsx`). Reproduce them exactly; do not
paraphrase, re-hyphenate, or re-case. The Python module is `ari_os`
(**underscore**); the product and repo dir are `ARI-OS` (**hyphen**). Do not
"fix" either. When the post and this pack disagree, the post wins — re-fetch
and re-extract.

---

## 1. One-line gist

ARI-OS installs **on top of Claude Code** (it does not replace it) via one
Python wizard module, writes a small predictable footprint (skills, command
shims, a statusline, a SessionStart hook, a managed CLAUDE.md block, and an
empty brain DB), and is **backed up and reversible** end-to-end.

---

## 2. NEEDLES (verbatim — do not confabulate)

### The install module (exact — run as a module, not a script)
- `python3 -m ari_os.install` — the wizard. Body says explicitly: "Run it as a
  module, not as a script." The module path is `ari_os.install` (**underscore**).
- Repo dir after clone is `ARI-OS` (**hyphen**); `cd ARI-OS` to enter it.

### Clone + install commands (exact)
- `git clone https://github.com/PUSHINGSQUARES/ARI-OS`
- `cd ARI-OS`
- `uv pip install -e .` — editable install (the InstallRitual "2. Install" step)
- `pip install -e .` — "If you do not use `uv`, plain `pip install -e .` works
  the same way."
- `pip install -e '.[media]'` — "For the optional media features, install the
  extra group." Note the quotes around `'.[media]'` are load-bearing in zsh.

### InstallRitual three steps (label → command, both exact)
1. `1. Clone` → `git clone https://github.com/PUSHINGSQUARES/ARI-OS`
2. `2. Install` → `uv pip install -e .`
3. `3. Run the wizard` → `python3 -m ari_os.install`

### Wizard flags (exact — from the body's flag list)
- `--llm ollama|api|off` — "sets how recall is powered. The default is `ollama`."
- `--ears` — "enables the optional listening surface."
- `--lens` — "enables the optional vision surface."
- `--no-mcp` — "skips automatic MCP registration."
- `--dry-run` — "shows what would change without writing anything."
- `--update` — "re-applies the latest managed files."
- `--revert` — "rolls the managed changes back."
- `--uninstall` — "removes everything ARI-OS placed."
- `--purge-keys` — "clears stored keys, used together with uninstall."

### What it installs (the footprint — exact counts + paths)
- 10 skills into `~/.claude/skills/<name>/SKILL.md`
- 10 command shims into `~/.claude/commands/<name>.md`
- A statusline in `settings.json`
- A SessionStart hook
- A managed block in your `CLAUDE.md`
- An empty brain database at `~/.ari-os/brain.db`
- Timestamped backups in `~/.ari-os/backups/<timestamp>/`

### MCP / Cortex registration (exact)
- MCP auto-registration is **on by default**; `--no-mcp` skips it.
- Server name: `ari-os-cortex`
- Auto-registered into three files:
  - `~/.claude/.mcp.json`
  - `~/.codex/config.toml`
  - `~/.gemini/settings.json`
- Manual add command (verbatim — note `python`, not `python3`, in the body):
  `claude mcp add ari-os-cortex -- python -m ari_os.tools.cortex.mcp_server stdio`
- The MCP server module path: `ari_os.tools.cortex.mcp_server`

### Keys (exact)
- Read from **environment variables first**, then the macOS Keychain.
- Keychain service name: `com.ari-os.keys`
- "They are never printed."

### Verify (exact)
- `python3 -m pytest -q` — test suite
- `python3 -m ari_os.tools.monitor` — open the monitor
- Monitor URL: `http://localhost:7777`
- Health check: "If the tests pass and the monitor loads, the install is healthy."

### Reversible commands (exact)
- `python3 -m ari_os.install --update` — re-applies the latest managed files.
- `python3 -m ari_os.install --revert` — rolls the managed changes back.
- `python3 -m ari_os.install --uninstall` — removes everything ARI-OS placed.
- Add `--purge-keys` to also clear stored keys (used together with `--uninstall`).

### Version + licence (exact)
- "ARI-OS is version 2.0.0, released under the PolyForm Noncommercial licence."
- NOTE: `content.ts` has `version: 'Software 1.0 · Now open-source'` — that is a
  **marketing headline string**, not a semver. The body's `2.0.0` is the actual
  software version. Do not conflate the two.

### Frontmatter (exact)
- `slug: install`
- `title: "Install ARI-OS"`
- `date: 2026-06-15`
- `folder: ari-os`
- `type: how-to`
- `status: published`
- `summary: "Clone, install, run the wizard, and verify. The install is backed up and reversible."`
- `related: [overview, using-it, brain]`

### Internal doc links (exact paths from the body)
- Overview: `/documents/ari-os/overview`
- Brain: `/documents/ari-os/brain`
- Using it: `/documents/ari-os/using-it`

### Diagram asset (exact)
- `src="/posts/ari-os/install-footprint.png"`
- `alt="What the installer places into your setup"`
- caption: "The footprint: skills, command shims, a statusline, a SessionStart
  hook, a managed block in CLAUDE.md, and an empty brain database. Backups are
  kept for each change."

### Pullquote (exact)
- `The install is backed up and reversible. You can always go back.`

### InstallRitual caption (exact)
- `Clone, install, run the wizard. Backed up and reversible.`

### FAQ (4 — exact Q/A)
- "What do I need?" → "Claude Code. ARI-OS sits on top of it and adds the
  orchestration layer and the local memory brain."
- "Can I remove it cleanly?" → "Yes. Run python3 -m ari_os.install --uninstall.
  It is backed up and reversible."
- "Where do my keys live?" → "Environment variables first, then the macOS
  Keychain under the service com.ari-os.keys. They are never printed."
- "Do I need Ollama?" → "It is optional. Without it, recall falls back to a
  ranked keyword search and the brain still works."

### Load-bearing prose (exact sentences)
- "ARI-OS installs on top of Claude Code. It does not replace it."
- "It adds an orchestrator-first layer and a local memory brain called Cortex."
- "Every change it makes is backed up first, so the whole install is reversible."
- "AI accelerates, it does not generate."
- "The installer is a Python module. Run it as a module, not as a script."

### Cross-file needles (from `content.ts`, used by `InstallCommands.tsx`)
- `ARI_OS.prerequisite` = `Requires Claude Code`
- `ARI_OS.reversibleNote` = `Backed up and reversible. Undo any time with
  python3 -m ari_os.install --uninstall.`
- `ARI_OS.setupHref` = `https://github.com/PUSHINGSQUARES/ARI-OS/blob/main/SETUP.md`
- `ARI_OS.githubUrl` = `https://github.com/PUSHINGSQUARES/ARI-OS`
- `ARI_OS.install[0]` label = `Run the wizard`; commands =
  [`git clone https://github.com/PUSHINGSQUARES/ARI-OS`,
  `cd ARI-OS && python3 -m ari_os.install`]

---

## 3. GIST (the procedure condensed)

The install is a **strictly additive layer on Claude Code** — never a
replacement. Three movements: **clone + editable-install** the Python package,
**run the wizard** (`python3 -m ari_os.install`, as a module), then **verify**
with the pytest suite and the monitor at `http://localhost:7777`.

The wizard's footprint is small and itemized: 10 skills, 10 command shims, a
statusline, a SessionStart hook, a managed block in `CLAUDE.md`, and an empty
brain DB at `~/.ari-os/brain.db`. MCP auto-registration (server `ari-os-cortex`)
is on by default and fans out to the Claude, Codex, and Gemini config files;
`--no-mcp` opts out. Flags let you choose the recall backend (`--llm
ollama|api|off`, default `ollama`), toggle the optional `--ears` / `--lens`
surfaces, and preview with `--dry-run`.

The through-line is **reversibility as a trust contract**. Every change is
backed up to `~/.ari-os/backups/<timestamp>/` before it is written, and the
same module drives `--update`, `--revert`, `--uninstall` (plus `--purge-keys`).
Keys are read from env vars first, then the macOS Keychain under
`com.ari-os.keys`, and never printed. The whole thing reduces to: nothing
destructive, nothing leaked, every action reversible.

---

## 4. KEY LEARNINGS

1. **Additive, not replacement.** ARI-OS sits on top of Claude Code; it does
   not replace it. Any framing that implies replacing the editor/model is wrong.
2. **Run the installer as a module.** `python3 -m ari_os.install` — the body
   insists on "as a module, not as a script." The module is `ari_os`
   (underscore); the repo dir is `ARI-OS` (hyphen). This mismatch is intentional
   and load-bearing.
3. **The footprint is itemized and small.** 10 skills + 10 command shims + a
   statusline + a SessionStart hook + a managed CLAUDE.md block + a brain DB.
   If an agent claims the installer touches anything else, it is confabulating.
4. **MCP is on by default and fans out to three config files.** The
   `ari-os-cortex` server lands in `~/.claude/.mcp.json`,
   `~/.codex/config.toml`, and `~/.gemini/settings.json`. `--no-mcp` is the
   opt-out; the manual add uses module `ari_os.tools.cortex.mcp_server`.
5. **Ollama is optional.** The default recall backend is `ollama`, but without
   it the brain falls back to ranked keyword search. Do not assert Ollama is
   required.
6. **Reversibility is contractual, not incidental.** `--update` / `--revert` /
   `--uninstall` / `--purge-keys` are first-class subcommands of the same
   module, and every write is preceded by a timestamped backup. Undo is the
   default expectation.
7. **Keys: env first, Keychain second, never printed.** The Keychain service is
   `com.ari-os.keys`. This is the same "nothing leaked" principle as the rest
   of the install.
8. **Verify is two steps, not one.** Passing tests (`python3 -m pytest -q`)
   alone is not health — the monitor (`python3 -m ari_os.tools.monitor`) must
   also load at `http://localhost:7777`.

---

## 5. FILE INDEX (load-bearing — re-fetch to verify needles)

Unlike the JSX-heavy sibling pages, **this post's needles live mostly in the
`.mdx` body itself** (it is prose + inline `<Code>` blocks), with supporting
literals in the shared component:

- `content/posts/ari-os/install.mdx` — primary
  source. Frontmatter (`slug: install`, `folder: ari-os`, `type: how-to`) plus
  all commands, wizard flags, the footprint list, MCP paths, key policy, verify
  steps, and the 4-item FAQ. **Most needles are here.**
- `components/ari-os/content.ts` — base `ARI_OS`
  object consumed by `InstallCommands.tsx`: `prerequisite`, `install` command
  group (label `Run the wizard`), `reversibleNote`, `setupHref`, `githubUrl`.
- `components/ari-os/InstallCommands.tsx` — the
  copy-to-clipboard install UI; renders `ARI_OS.install` commands and links to
  `setupHref` ("Read SETUP.md").
- `public/posts/ari-os/install-footprint.png` — the
  footprint diagram (`Diagram src`).

External refs to re-fetch if stale:
- `https://github.com/PUSHINGSQUARES/ARI-OS` — repo (verify public + cloneable).
- `https://github.com/PUSHINGSQUARES/ARI-OS/blob/main/SETUP.md` — verify the
  manual-setup doc path is still `main`/`SETUP.md`.

> Backfilled 2026-07-18 from the published body; not needle-extracted at thought-time.