# @mosaicstack/mosaic

CLI package for the Mosaic self-hosted AI agent platform.

## Usage

```bash
mosaic wizard           # First-run setup wizard
mosaic gateway install  # Install the gateway daemon
mosaic config show      # View current configuration
mosaic config hooks list  # Manage Claude hooks
```

## Headless / CI Installation

Set `MOSAIC_ASSUME_YES=1` (or ensure stdin is not a TTY) to skip all interactive prompts. The following environment variables control the install:

### Gateway configuration (`mosaic gateway install`)

| Variable                   | Default                 | Required           |
| -------------------------- | ----------------------- | ------------------ |
| `MOSAIC_STORAGE_TIER`      | `local`                 | No                 |
| `MOSAIC_GATEWAY_PORT`      | `14242`                 | No                 |
| `MOSAIC_DATABASE_URL`      | _(none)_                | Yes if tier=`team` |
| `MOSAIC_VALKEY_URL`        | _(none)_                | Yes if tier=`team` |
| `MOSAIC_ANTHROPIC_API_KEY` | _(none)_                | No                 |
| `MOSAIC_CORS_ORIGIN`       | `http://localhost:3000` | No                 |

### Admin user bootstrap

| Variable                | Default  | Required       |
| ----------------------- | -------- | -------------- |
| `MOSAIC_ADMIN_NAME`     | _(none)_ | Yes (headless) |
| `MOSAIC_ADMIN_EMAIL`    | _(none)_ | Yes (headless) |
| `MOSAIC_ADMIN_PASSWORD` | _(none)_ | Yes (headless) |

`MOSAIC_ADMIN_PASSWORD` must be at least 8 characters. In headless mode a missing or too-short password causes a non-zero exit.

### Example: Docker / CI install

```bash
export MOSAIC_ASSUME_YES=1
export MOSAIC_ADMIN_NAME="Admin"
export MOSAIC_ADMIN_EMAIL="admin@example.com"
export MOSAIC_ADMIN_PASSWORD="securepass123"

mosaic gateway install
```

## Runtime launchers

```bash
mosaic claude            # Launch Claude Code with Mosaic injection
mosaic yolo claude       # …with --dangerously-skip-permissions
mosaic codex | opencode | pi
```

### `mosaic claudex` (EXPERIMENTAL)

Runs GPT models **inside the Claude Code harness** by pointing Claude Code at a
local [`claude-code-proxy`](https://github.com/raine/claude-code-proxy) that
translates the Anthropic Messages API to a ChatGPT-subscription (Codex OAuth)
backend. This is **not Anthropic Claude** — model behavior, tool use, and output
quality may differ. Intended for evaluation, not production delivery.

```bash
mosaic claudex           # launch (prompts through the proxy readiness gate)
mosaic yolo claudex      # …with --dangerously-skip-permissions
mosaic claudex --print "hello"   # trailing args are forwarded to Claude Code
```

**Prerequisite:** the `claude-code-proxy` binary must be installed and
authenticated (`claude-code-proxy codex auth …`). `mosaic claudex` runs a
preflight that verifies the binary, the OAuth state (triggering a device re-auth
if needed), and a trusted local listener before launching; it **fails closed**
if the proxy cannot be brought up with a verified identity.

**Isolation (never touches your real Claude state).** claudex always launches
against an isolated `CLAUDE_CONFIG_DIR` (default `~/.config/mosaic/claudex/home`).
The ambient `CLAUDE_CONFIG_DIR` is deliberately ignored, and a guard proves the
resolved dir can never be — or live under — the real `~/.claude`. A claudex
session therefore cannot mutate your normal Claude Code config.

**No token leakage.** claudex never reads the proxy's credential file. Claude
Code is handed only `ANTHROPIC_AUTH_TOKEN=unused` pointed at the loopback proxy;
the entire credential-bearing env family (`ANTHROPIC_*`, `AWS_*`, `GOOGLE_CLOUD_*`,
`GOOGLE_APPLICATION_CREDENTIALS`, `*_TOKEN`, `*_KEY`, `*_SECRET`, …) is stripped
from the composed environment. The Bedrock/Vertex routing switches
(`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, and the `_SKIP_*_AUTH`
pair) are force-removed regardless of value — otherwise their mere presence
would route Claude Code to the real Anthropic API via AWS/GCP and bypass the
proxy. The proxy holds the real OAuth credential.

**Model tiers (override via env).**

| Tier                  | Env var                      | Default        |
| --------------------- | ---------------------------- | -------------- |
| primary (opus/sonnet) | `ANTHROPIC_MODEL`            | `gpt-5.6-sol`  |
| small/fast (haiku)    | `ANTHROPIC_SMALL_FAST_MODEL` | `gpt-5.6-luna` |

Operator-provided values win over the defaults. Additional overrides:
`MOSAIC_CLAUDEX_CONFIG_DIR` (isolated config dir), `ANTHROPIC_BASE_URL` (proxy
endpoint).

## Hooks management

After running `mosaic wizard`, Claude hooks are installed in `~/.claude/hooks-config.json`.

```bash
mosaic config hooks list              # Show all hooks and enabled/disabled status
mosaic config hooks disable PostToolUse  # Disable a hook (reversible)
mosaic config hooks enable PostToolUse   # Re-enable a disabled hook
```

Set `CLAUDE_HOME` to override the default `~/.claude` directory.