---
source_hash: 70de6ba9cdc906ef255ea33320f548bbe72da234387deb83f2191f62366d60e8
post: /posts/ari-os/install
shape: doctrinal
---

# Context Pack: Install ARI-OS

Agent reference for the rewritten Claude Code install guide. Only quoted excerpts are verbatim. Behaviour corrections come from public source commit 85bba5fccf42549b0507bc852ac8aaf47844b812, not an executed installer test. No installation or lifecycle command was run for this review.

## Verbatim excerpts

> The checked package requires Python 3.10 or newer.

> Key values should never appear in reports or shared logs.

> This installer uses a manifest and backups; it does not give you a one-commit undo guarantee.

## Install path and interface

Original sequence: clone `https://github.com/PUSHINGSQUARES/ARI-OS`, enter `ARI-OS`, install with `uv pip install -e .`, then run `python3 -m ari_os.install`. Fallback: `pip install -e .`; optional media group: `pip install -e '.[media]'`. Keep the dependency-install step before the wizard.

The nine original flags are `--llm ollama|api|off` (default ollama), `--ears`, `--lens`, `--no-mcp`, `--dry-run`, `--update`, `--revert`, `--uninstall`, and `--purge-keys` used with uninstall. The llm flag persists cortex.llm; direct embedding retrieval does not use it, so off does not establish that embedding calls stop. Newer source also supports `--target claude|codex|gemini|kimi|custom` and `--dir` for custom configuration.

The original guide's ten skills and ten shims are historical counts. The installer discovers the files in its checkout. Claude locations are `~/.claude/skills/<name>/SKILL.md` and `~/.claude/commands/<name>.md`, plus statusline settings, SessionStart hook, managed `CLAUDE.md`, `~/.ari-os/brain.db` and timestamped backups under `~/.ari-os/backups/<timestamp>/`.

## Backups and lifecycle: actual scope

Backups are attempted before managed writes but are best effort; writes may continue if backup creation fails. Inspect the manifest and actual copies before trusting recovery.

Revert uses the latest manifest. It restores recorded backups or removes recorded destinations with no backup recorded, subject to root/checksum checks. That includes a pre-existing file whose backup failed. Restoring whole files can replace later manual edits. Brain bootstrap/configuration changes are outside that file manifest. Uninstall unregisters the integration and invokes revert; it does not remove everything created by setup.

Installer `--update` reapplies the local checkout and may migrate the brain database. It replaces the manifest; it is not a fetch-new-release operation. `--purge-keys` removes state-home config.json only, not environment or macOS Keychain keys. Key lookup order is environment then service `com.ari-os.keys`.

Static source inspection found a tuple-shape mismatch in default dry-run MCP output. `--dry-run --no-mcp` avoids that path; runtime success was not tested. A failed preview does not establish that no changes were planned.

## MCP and verification

Automatic MCP registration is on unless `--no-mcp` is supplied. Server name: `ari-os-cortex`. Documented locations: `~/.claude/.mcp.json`, `~/.codex/config.toml`, `~/.gemini/settings.json`. For a Claude install, Codex/Gemini directories must exist or be explicitly configured. Automatic Kimi registration additionally requires `KIMI_CODE_HOME`; an explicit Kimi target follows its own path. Do not promise that all files appear on every install.

Manual Claude registration remains `claude mcp add ari-os-cortex -- python -m ari_os.tools.cortex.mcp_server stdio`, using the environment with package dependencies installed.

Checks: `python3 -m pytest -q`, then `python3 -m ari_os.tools.monitor`, with the monitor at `http://localhost:7777`. Also verify the actual memory/backend integration required; a dashboard is not proof of every optional capability.

Historical version: 2.0.0. Checked source version: 2.3.0. Licence: PolyForm Noncommercial License 1.0.0. The inspected retrieve path calls Ollama embeddings before full-text search and can fail before reaching it. A working no-Ollama keyword fallback was not established; this is source inspection, not a runtime reproduction.

[Checked installer](https://github.com/PUSHINGSQUARES/ARI-OS/blob/85bba5fccf42549b0507bc852ac8aaf47844b812/ari_os/install.py) · [Daily guide](/documents/ari-os/using-it).