rex-cli

# RexCLI (AIOS)

This repository provides a local-first agent workflow for `Codex CLI`, `Claude Code`, and `Gemini CLI`.
It does not replace those clients. Instead, it adds three shared capabilities:

1. Unified browser automation via Playwright MCP (`browser_*` tools)
2. Cross-CLI filesystem Context DB for resumable task memory
3. Privacy Guard redaction before reading config/secret-like files (`~/.rexcil/privacy-guard.json`)

## Start Here (Use First, Read Later)

Key links:

- Project (GitHub): `https://github.com/rexleimo/rex-cli`
- Docs: `https://cli.rexai.top`
- Blog: `https://cli.rexai.top/blog/`
- Case Library: `https://cli.rexai.top/case-library/`
- Friend sites: `https://os.rexai.top` / `https://rexai.top` / `https://tool.rexai.top`

30-second install (recommended, GitHub Releases):

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

30-second install (Windows PowerShell):

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

Recommended TUI walkthrough (best first run):

1. Launch `aios`
2. Choose `Setup` in the full-screen menu
3. Pick the component set that matches your goal:
   - `all` for the full stack
   - `shell,skills,superpowers` for memory + skills first
   - `browser` for Browser MCP only
4. Run `Doctor` before leaving the TUI

Alternative: git clone (dev-friendly):

Lifecycle note:

- `node scripts/aios.mjs` is now the canonical implementation path.
- `scripts/aios.sh` / `scripts/aios.ps1` and `setup-all/update-all/verify-aios` remain supported as thin compatibility wrappers.

macOS / Linux:

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

Windows PowerShell:

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

## Why does `codex` load ContextDB automatically?

The mechanism is **transparent zsh wrapping**:

- [`scripts/contextdb-shell.zsh`](scripts/contextdb-shell.zsh) defines shell functions for `codex()`, `claude()`, and `gemini()`
- Those functions delegate to [`scripts/contextdb-shell-bridge.mjs`](scripts/contextdb-shell-bridge.mjs), which decides wrap vs passthrough
- When wrapping is enabled, the bridge calls [`scripts/ctx-agent.mjs`](scripts/ctx-agent.mjs) with the current git root as `--workspace`, or the current directory when Git root detection is unavailable
- Outside git projects, the bridge can fall back to the current directory as workspace; management subcommands (for example `codex mcp`, `gemini hooks`) still pass through unchanged

So you keep using the same command names and normal interactive flow.

## Automatic First Task Bootstrap

On the first `codex`/`claude`/`gemini` run in a workspace, AIOS now auto-creates a lightweight bootstrap task when:

- `tasks/.current-task` is missing or empty
- `tasks/pending/` has no non-hidden entries

Generated files:

- `tasks/pending/task_<timestamp>_bootstrap_guidelines/task.json`
- `tasks/pending/task_<timestamp>_bootstrap_guidelines/prd.md`
- `tasks/.current-task`

Disable options:

- Global: `export AIOS_BOOTSTRAP_AUTO=0`
- Per invocation: `scripts/ctx-agent.mjs ... --no-bootstrap`

## Operator Toolkit (Quality Gate / Learn-Eval / Orchestrate)

These commands are designed to keep the workflow local-first and predictable before you plug in any real parallel model runtime.

### Quality Gate (repo health + ContextDB regression guard)

Run the full gate:

```bash
aios quality-gate full
```

Run a stricter pre-PR gate:

```bash
aios quality-gate pre-pr --profile strict
```

Disable a specific check (comma-separated):

```bash
AIOS_DISABLED_GATES=quality:contextdb aios quality-gate pre-pr
```

### Learn-Eval (turn checkpoint telemetry into recommendations)

```bash
aios learn-eval --limit 10
aios learn-eval --session <session-id> --format json
```

### Orchestrate (blueprints + local dispatch skeleton + token-free dry-run)

Preview a blueprint:

```bash
aios orchestrate feature --task "Ship X"
```

Build a local dispatch plan (no model calls, no execution):

```bash
aios orchestrate --session <session-id> --dispatch local --execute none --format json
```

Simulate execution locally (still no model calls):

```bash
aios orchestrate --session <session-id> --format json
# optional: run supported gate/runbook actions before final DAG selection
aios orchestrate --session <session-id> --preflight auto --format json
```

Execute live via CLI subagents (token cost, opt-in; currently codex-only):

```bash
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 structured exec outputs. AIOS will auto-use `codex exec` with `--output-schema` + `--output-last-message` + stdin when available, and fall back to stdout parsing for older versions.

### Context Pack Fail-Open (prevent wrapper hard failures)

By default, `ctx-agent` will **warn and continue** if `contextdb context:pack` fails (it will run the CLI without injected context rather than crashing).

If you want to make context packet failures fatal:

```bash
export CTXDB_PACK_STRICT=1
```

Shell wrappers (`codex`/`claude`/`gemini`) default to fail-open even if `CTXDB_PACK_STRICT=1` is set (so interactive sessions don't get bricked). To enforce strict packing for wrapped CLI runs too:

```bash
export CTXDB_PACK_STRICT_INTERACTIVE=1
```

## Architecture

```text
User -> codex/claude/gemini
     -> (zsh wrapper: contextdb-shell.zsh)
     -> contextdb-shell-bridge.mjs
     -> ctx-agent.mjs
        -> contextdb CLI (init/session/event/checkpoint/pack)
        -> start native codex/claude/gemini (with context packet)
     -> mcp-server/browser_* (optional browser automation)
```

## Repository Layout

- `mcp-server/`: Playwright MCP service and `contextdb` CLI implementation
- `scripts/contextdb-shell-bridge.mjs`: Cross-platform wrap/passthrough decision bridge
- `scripts/ctx-agent.mjs`: Unified runner that integrates ContextDB
- `scripts/contextdb-shell.zsh`: Transparent wrappers for `codex/claude/gemini`
- `scripts/privacy-guard.mjs`: Privacy guard config + redaction CLI (`init/status/set/redact`)
- `agent-sources/`: canonical orchestrator agent source tree
- `memory/specs/orchestrator-agents.json`: generated compatibility export for orchestrator/runtime consumers
- `.claude/agents` / `.codex/agents`: generated repo-local agent catalogs owned by `node scripts/generate-orchestrator-agents.mjs`
- `memory/context-db/`: Runtime session artifacts for this repo (ignored by git)
- `config/browser-profiles.json`: Browser profile/CDP config
- `examples/`: Minimal runnable examples for ContextDB, Browser MCP smoke, and orchestrate dry-run workflows

Agent catalog note:

- Run `node scripts/generate-orchestrator-agents.mjs` to regenerate the compatibility export plus repo-local agent catalogs.
- Run `node scripts/generate-orchestrator-agents.mjs --export-only` to refresh only `memory/specs/orchestrator-agents.json`.
- `gemini` and `opencode` client selections still reuse the Claude/Codex compatibility catalogs in v1; they do not have native repo agent roots yet.

## Prerequisites

- Git
- Node.js **22 LTS** with `npm`
- Windows: PowerShell (Windows PowerShell 5.x or PowerShell 7)
- Optional (docs only): Python 3.10+ for MkDocs (`pip install -r docs-requirements.txt`)

## Quick Start

Before running any `scripts/*.sh` or `scripts/*.ps1` commands, clone and enter this repository:

```bash
git clone https://github.com/rexleimo/rex-cli.git
cd rex-cli
```

## Official Case Library

If you want concrete, reproducible examples of what this repo can do, start here:

- Docs site: `https://cli.rexai.top/case-library/`
- Repo doc: [`docs-site/case-library.md`](docs-site/case-library.md)

### 1) Recommen

[truncated…]