Skip to content

Quick Start

This page combines macOS, Linux, and Windows setup into one flow. Use the OS tabs when commands differ.

RexCLI lets you keep using codex, claude, and gemini directly while adding project-scoped ContextDB memory and unified browser MCP setup.

Prerequisites

  • Node.js 22 LTS and npm
  • At least one CLI installed: codex, claude, or gemini
  • A project/workspace directory where you want project-scoped ContextDB memory

This repo installs to ~/.rexcil/rex-cli. The unified entry is aios:

  • aios (no args) opens the interactive full-screen TUI
  • aios doctor|update|privacy ... keeps working as before

Option C: One-liner installer (GitHub Releases)

This is the stable installation path and depends on published GitHub Release assets.

curl -fsSL https://github.com/rexleimo/rex-cli/releases/latest/download/aios-install.sh | bash
source ~/.zshrc
aios

irm https://github.com/rexleimo/rex-cli/releases/latest/download/aios-install.ps1 | iex
. $PROFILE
aios

Option A: git clone (dev-friendly)

Use this only when you explicitly want unreleased main branch behavior. This is the supported development install path, not the stable release path.

git clone https://github.com/rexleimo/rex-cli.git ~/.rexcil/rex-cli
cd ~/.rexcil/rex-cli
scripts/aios.sh

git clone https://github.com/rexleimo/rex-cli.git $HOME\.rexcil\rex-cli
cd $HOME\.rexcil\rex-cli
powershell -ExecutionPolicy Bypass -File .\scripts\aios.ps1

Option B: Download from GitHub Releases (offline-friendly)

Download rex-cli.tar.gz (macOS/Linux) or rex-cli.zip (Windows) from Releases and extract to ~/.rexcil/. Then run scripts/aios.sh / scripts/aios.ps1.

TUI Welcome Banner

When you start the TUI with aios, you'll see a cyan ASCII art banner:

  ╔══════════════════════════════════════════╗
  ║   ██████╗ ██╗  ██╗██╗██████╗  ██████╗    ║
  ║   ██╔══██╗██║ ██╔╝██║██╔══██╗██╔════╝    ║
  ║   ██████╔╝█████╔╝ ██║██████╔╝██║         ║
  ║   ██╔══██╗██╔═██╗ ██║██╔══██╗██║         ║
  ║   ██║  ██║██║  ██╗██║██║  ██║╚██████╗    ║
  ║   ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝ ╚═════╝    ║
  ║          Hello, Rex CLI!                 ║
  ╚══════════════════════════════════════════╝

This confirms the TUI is ready and shows the repository location below the banner.

After install, use the TUI as the main onboarding path for this release:

  1. Run aios
  2. Select Setup
  3. Choose your component set:
  4. all for the full stack
  5. shell,skills,superpowers for shared memory + skills first
  6. browser for Browser MCP only
  7. If you enable Skills, the picker now helps distinguish states:
  8. setup/update mark already-installed skills with (installed)
  9. uninstall shows only installed skills, supports scrolling, and offers Select all / Clear all
  10. installs default to portable copy mode; use --install-mode link only when you intentionally want a local-dev link back to this repo
  11. When setup finishes, run Doctor in the same TUI
  12. Reload your shell if you installed shell wrappers:
  13. macOS / Linux: source ~/.zshrc
  14. Windows PowerShell: . $PROFILE

Repo contributors: skills now come from skill-sources/

If you are editing this repo itself rather than just installing it:

  • canonical skill source files live under skill-sources/
  • repo-local .codex/skills, .claude/skills, .agents/skills, .gemini/skills, and .opencode/skills are generated compatibility outputs
  • regenerate them with:
node scripts/sync-skills.mjs
node scripts/check-skills-sync.mjs

0.1 Privacy Guard Strict Read (enabled by default)

Shell setup now initializes Privacy Guard config at ~/.rexcil/privacy-guard.json and enables strict redaction policy by default. For config or secret-like files, use the strict read path:

aios privacy read --file <path>

aios privacy read --file <path>

Optional local model path (Ollama + qwen3.5:4b):

aios privacy ollama-on

aios privacy ollama-on

Component selection examples:

Tip: if you installed via the one-liner, the repo lives at ~/.rexcil/rex-cli. Run the scripts from that directory, or just run aios and pick Setup in the TUI.

# only shell wrappers + skills
scripts/setup-all.sh --components shell,skills --mode opt-in

# only browser MCP
scripts/setup-all.sh --components browser

powershell -ExecutionPolicy Bypass -File .\scripts\setup-all.ps1 -Components shell,skills -Mode opt-in
powershell -ExecutionPolicy Bypass -File .\scripts\setup-all.ps1 -Components browser

One-command update/uninstall:

scripts/update-all.sh --components all --mode opt-in
scripts/uninstall-all.sh --components shell,skills

powershell -ExecutionPolicy Bypass -File .\scripts\update-all.ps1 -Components all -Mode opt-in
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-all.ps1 -Components shell,skills

If you prefer component-by-component setup, continue with steps 1-8 below.

1) Install Browser MCP

scripts/install-browser-mcp.sh
scripts/doctor-browser-mcp.sh

powershell -ExecutionPolicy Bypass -File .\scripts\install-browser-mcp.ps1
powershell -ExecutionPolicy Bypass -File .\scripts\doctor-browser-mcp.ps1

2) Build ContextDB CLI

cd mcp-server
npm install
npm run build

scripts/install-contextdb-shell.sh --mode opt-in
scripts/doctor-contextdb-shell.sh
source ~/.zshrc

powershell -ExecutionPolicy Bypass -File .\scripts\install-contextdb-shell.ps1 -Mode opt-in
powershell -ExecutionPolicy Bypass -File .\scripts\doctor-contextdb-shell.ps1
. $PROFILE

4) Enable current project

touch .contextdb-enable

New-Item -ItemType File -Path .contextdb-enable -Force

5) Start working

cd /path/to/your/project
codex
# or
claude
# or
gemini

5.1) Optional: operator tools (quality gate + learn-eval + orchestrate)

Repo health gate (includes ContextDB regression checks):

aios quality-gate pre-pr --profile strict

Analyze the latest session telemetry:

aios learn-eval --limit 10

Build a local orchestration skeleton (no model calls):

aios orchestrate --session <session-id> --preflight auto --format json

Execute live via CLI subagents (token cost, opt-in):

export AIOS_EXECUTE_LIVE=1
export AIOS_SUBAGENT_CLIENT=codex-cli  # required (codex-only live runtime)
aios orchestrate --session <session-id> --dispatch local --execute live --format json

Tip (codex-cli): Codex CLI v0.114+ supports codex exec structured outputs (--output-schema, --output-last-message, stdin). AIOS uses them when available and falls back to stdout parsing on older versions.

Optional controls:

  • AIOS_SUBAGENT_CONCURRENCY (default: 2)
  • AIOS_SUBAGENT_TIMEOUT_MS (default: 600000)

5.2) Optional: HUD and Team Ops visibility

View session status with HUD:

aios hud --provider codex
aios hud --watch --preset full
aios hud --session <session-id> --json

Team Ops status and history:

aios team status --provider codex --watch
aios team history --provider codex --limit 20

Skill-candidate detail view (2026-04-09+):

# Show skill candidates with default limit (6 in normal mode, 3 in fast-watch minimal)
aios team status --show-skill-candidates

# Configure candidate limit (1-20)
aios team status --show-skill-candidates --skill-candidate-limit 10

# Fast-watch mode auto-uses minimal limit (3 candidates)
aios team status --watch --fast

# HUD also supports skill-candidate view
aios hud --show-skill-candidates --skill-candidate-limit 5

Quality-gate category filters (2026-04-08+):

# Show only quality-gate failed sessions
aios team history --quality-failed-only

# Filter by quality category prefix
aios team history --quality-category clarity
aios team history --quality-category sample.latency-watch

Dispatch hindsight and draft recommendations (2026-04-07+):

# Learn-eval shows draft skill-candidate patches
aios learn-eval --limit 10

# HUD suggests skill-candidate apply commands when available
aios hud --session <session-id>

6) Verify data created

ls memory/context-db

Get-ChildItem memory/context-db

You should see sessions/, index/, and exports/.

7) Update / Uninstall wrappers

scripts/update-contextdb-shell.sh --mode opt-in
scripts/uninstall-contextdb-shell.sh

powershell -ExecutionPolicy Bypass -File .\scripts\update-contextdb-shell.ps1 -Mode opt-in
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-contextdb-shell.ps1

8) Optional: install project skills globally

Use this only when you want this repo's skills available in other projects. --client all installs for codex, claude, gemini, and opencode.

scripts/install-contextdb-skills.sh --client all
scripts/doctor-contextdb-skills.sh --client all

powershell -ExecutionPolicy Bypass -File .\scripts\install-contextdb-skills.ps1 -Client all
powershell -ExecutionPolicy Bypass -File .\scripts\doctor-contextdb-skills.ps1 -Client all

Skill lifecycle:

scripts/update-contextdb-skills.sh --client all
scripts/uninstall-contextdb-skills.sh --client all

powershell -ExecutionPolicy Bypass -File .\scripts\update-contextdb-skills.ps1 -Client all
powershell -ExecutionPolicy Bypass -File .\scripts\uninstall-contextdb-skills.ps1 -Client all

FAQ

Does this replace native CLI clients?

No. You still run native commands. The wrapper only injects context and keeps compatibility.

How do I avoid cross-project memory contamination?

Use CTXDB_WRAP_MODE=opt-in and create .contextdb-enable only in the projects you want.

Does wrapper install also install skills?

No. Wrappers and skills are separate on purpose. Use step 8 when you want global skills.

Why do I see CODEX_HOME points to ".codex"?

CODEX_HOME was set to a relative path. Use an absolute path:

export CODEX_HOME="$HOME/.codex"
mkdir -p "$CODEX_HOME"

Which command should I run first if browser tools fail?

Run doctor-browser-mcp first (scripts/doctor-browser-mcp.sh or doctor-browser-mcp.ps1).