Ari’s Space*   est. 2026
Skip to content
ari*s space[ a. ]
← Libraryari os / 2026-06-15

Install ARI-OS

The Claude Code installation path, its managed files and verification steps, with the actual scope of backups, rollback and key handling.

8 parts / Hover to explore. Click to read.

The Claude Code installation path, its managed files and verification steps, with the actual scope of backups, rollback and key handling.

Check version + dependencies
             |
Inspect planned managed changes
             |
Install -> journal + backups
             |
Verify the intended integration

Rollback: inspect actual scope
Installation needs its own integration check. Backups are attempted rather than guaranteed, and rollback is not a complete snapshot of the machine.
Context Pack (for agents)

This is the Claude Code installation path. ARI-OS adds the working conventions, background dispatch and local Cortex memory around that setup.

The original June guide covered version 2.0.0. The public source checked for this revision declares 2.3.0. Keep the commands below with the version's own help and setup notes; newer installer targets don't make every harness support the same features.

Install ritualInstall1git clone https://github.com/PUSHINGSQUARES/ARI-OS1. Clone2uv pip install -e .2. Install3python3 -m ari_os.install3. Run the wizard
Clone, install the package, inspect the wizard and its managed changes.

Read the overview first if you want to understand the division between your main session and its workers.

Get the package before running the wizard

Clone the repository, enter it and install the editable package with its dependencies.

git clone https://github.com/PUSHINGSQUARES/ARI-OS
cd ARI-OS
uv pip install -e .

The checked package requires Python 3.10 or newer. Without uv, use pip install -e .. The optional media dependency group is pip install -e '.[media]'.

Inspect the managed changes

Run the installer as a Python module.

python3 -m ari_os.install

The original wizard flags remain useful reference points:

  • --llm ollama|api|off saves the Cortex LLM setting; the default is ollama. The inspected direct embedding path does not use this choice, so --llm off is not a promise that recall makes no embedding calls.
  • --ears opts into the audio surface.
  • --lens opts into the LENS surface.
  • --no-mcp skips automatic MCP registration.
  • --dry-run reports the planned managed changes without applying them.
  • --update reapplies managed files from the local checkout.
  • --revert reverses the changes recorded in the install manifest.
  • --uninstall unregisters the managed integration and invokes that revert path.
  • --purge-keys, used with uninstall, needs particular care: in the checked implementation it removes the state configuration file. It does not clear environment variables or macOS Keychain entries.

The checked installer also accepts --target claude|codex|gemini|kimi|custom and --dir for a custom configuration root. This page follows the Claude target; consult the installed version's help for other targets.

Source inspection also found a problem in the checked default dry-run: its MCP records have a different tuple shape from the final output loop. --dry-run --no-mcp avoids that particular path, but this review did not execute the installer. Treat a failed preview as a failed preview, not proof that there are no planned changes.

Know the footprint

The June guide described ten skills and ten command shims. For the Claude setup, their locations are ~/.claude/skills/<name>/SKILL.md and ~/.claude/commands/<name>.md.

The rest of the footprint includes a statusline in settings.json, a SessionStart hook, a managed block in CLAUDE.md, the brain database at ~/.ari-os/brain.db and timestamped backups under ~/.ari-os/backups/<timestamp>/.

What the installer places into your setup
Skills, command shims, statusline, SessionStart hook, a managed instruction block and local brain storage. Inspect the managed changes and their backups.

The installer attempts backups before changing managed files and records the changes. The checked code can continue when a backup attempt fails, so the old promise that every change always has a recoverable copy was too broad. Inspect the journal and the actual backups before relying on a rollback. The pinned installer source shows that boundary.

Connect Cortex through MCP

Automatic registration is on unless you pass --no-mcp. The server is named ari-os-cortex.

The documented locations are ~/.claude/.mcp.json, ~/.codex/config.toml and ~/.gemini/settings.json. For the Claude install path, Codex and Gemini registration depends on their configuration directories being present or explicitly configured; don't assume all three files will be created on every machine. Automatic Kimi registration additionally requires KIMI_CODE_HOME; merely having ~/.kimi-code is not enough. An explicit Kimi target uses its own registration path.

For manual Claude registration, the original command is:

claude mcp add ari-os-cortex -- python -m ari_os.tools.cortex.mcp_server stdio

Use the Python environment where the package and its dependencies are installed. The brain guide covers the memory behaviour after connection.

Keep key handling separate from rollback

The documented resolution order is environment variables first, then the macOS Keychain service com.ari-os.keys. Key values should never appear in reports or shared logs.

An installer rollback is not a way to revoke a provider key. In particular, the --purge-keys implementation described above does not remove Keychain or environment values.

That illustration shows the idea of reversing a change. This installer uses a manifest and backups; it does not give you a one-commit undo guarantee.

Verify the resulting setup

Run the package's tests and open the monitor.

python3 -m pytest -q
python3 -m ari_os.tools.monitor

The monitor uses http://localhost:7777. Passing tests and a working monitor are useful checks. Also verify the integration you intend to use: a successful memory call, for example, rather than assuming the dashboard proves every optional backend works.

Understand the way back

python3 -m ari_os.install --update reapplies the current checkout's managed files. python3 -m ari_os.install --revert uses the recorded manifest and backups. python3 -m ari_os.install --uninstall unregisters the integration and runs the revert path.

The revert path can restore recorded backups and remove a recorded destination whenever no backup is recorded. That includes a pre-existing file whose backup attempt failed. Restoring a whole file can replace later manual edits. Brain bootstrap and configuration changes are not recorded in that file manifest, so uninstall does not remove everything the setup created. An update replaces the current manifest and can migrate the brain database.

This isn't a general snapshot of your machine. Keep the journal and backups you need, and inspect their scope before using a destructive lifecycle command.

Check what changed. Keep the evidence needed to restore it.
What do I need for this guide?
Claude Code and the installed ARI-OS Python package with its dependencies. Optional media and model features have additional requirements.
Can I remove the integration?
The installer provides --uninstall and --revert. Inspect the recorded changes and backups first; they cover the managed integration, not a complete machine snapshot.
Where do keys resolve from?
Environment variables first, then the macOS Keychain service com.ari-os.keys. Uninstall with --purge-keys does not revoke those provider keys.
Do I need Ollama?
The original guide promised keyword recall without it. The inspected retrieval path calls Ollama embeddings before full-text search and can fail there; a working fallback is not established. Check the brain guide and your installed version.

ARI-OS uses the PolyForm Noncommercial licence. Continue with using it day to day once you've checked the installed state.

//

[ comments ]

guests welcome. members show first in the list

no comments yet. start the thread_

1 / 10