install

Five minutes to an AI that remembers.

nixfredOS installs itself, and it asks before every change. Here is exactly what you need and exactly what happens.

step 0 · requirements

Required

  • macOS 13+ or a modern Linux (Arch, Ubuntu, Debian, Fedora…)
  • git and curl
  • bun 1.2+. The installer can install it for you
  • gh (GitHub CLI) and a free GitHub account
  • An AI coding harness. Claude Code is the most tested. Cursor, Cline, Codex and Gemini CLI can follow the guide

Optional

  • Ollama for semantic, meaning-based recall. A native app, no containers
  • An ElevenLabs key if you want spoken responses

No Docker. No telemetry. No cloud memory service.

step 1 · preflight (installs nothing)

Check your machine first

Runs the installer's checks and prints what is present and what is missing, then exits.

$ curl -fsSL https://raw.githubusercontent.com/nixfred/nixfredOS/main/nixfredOS/install/install.sh | bash -s -- --check

step 2 · install

Option A: let your AI do it

Paste this into your AI coding assistant. It reads the guide and walks you through everything.

you › Read https://github.com/nixfred/nixfredOS/blob/main/nixfredOS/INSTALL.md and install nixfredOS for me.

Option B: one line in a terminal

$ curl -fsSL https://raw.githubusercontent.com/nixfred/nixfredOS/main/nixfredOS/install/install.sh | bash

what happens

Six steps. You approve each one.

  1. 1

    Preflight

    Checks for curl, git, bash, tar, bun and gh, and detects macOS or Linux. Offers to install bun if it is missing.

  2. 2

    Find your harness

    Locates your AI harness's skills folder. An existing install is detected and upgraded, including an old LifeOS setup.

  3. 3

    Fetch, pinned

    Resolves the latest release, pins it to an exact commit and prints the sha256 of the download before extracting anything.

  4. 4

    Install additively

    Drops the nixfredOS skill into place. Nothing else on your machine is touched until you say yes.

  5. 5

    Memory engine

    Sets up the SQLite FTS5 memory engine with empty memory. If Ollama is present, it offers local semantic recall.

  6. 6

    Your private brain

    Walks you through gh login and creates a PRIVATE GitHub repo for your AI's config and memory. It verifies the repo is private before the first push.

your private brain repo

Why GitHub, and why private

Your AI's memory is just files: settings, hooks, notes, decisions. Committing them to git gives you history, backup and a searchable record of everything your AI has learned. Recall becomes git log --grep.

The installer and your AI will:

  • install gh if needed (Homebrew on macOS, your package manager on Linux)
  • run gh auth login with you at the keyboard
  • create <you>/<name>-brain as a private repo
  • check it really is private before the first push, and refuse to push anywhere public

after install

Give it a name, then give it time

Onboarding is a conversation. Your AI asks about your goals (current state and ideal state), detects conflicts with your existing setup, and wires hooks only with your permission.

Then just work. Say remember that when something matters. In a week, ask it what you decided. In a month, notice you stopped re-explaining yourself.

Upgrading? Re-run the installer. It detects your existing install and upgrades it in place.

Want a guide for the first setup? nixfred helps people 1:1 as a paid consultant. The software stays free.