# Mosaic Agent Framework

Universal agent standards layer for Claude Code, Codex, OpenCode, and Pi.

One config, every runtime, same standards.

> **This is the framework component of [mosaic-stack](https://git.mosaicstack.dev/mosaic/mosaic-stack).** No personal data, credentials, user-specific preferences, or machine-specific paths should be committed. All personalization happens at install time via `mosaic init` or by editing files in `~/.config/mosaic/` after installation.

## Quick Install

### Mac / Linux

```bash
bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
```

### Windows (PowerShell)

```powershell
# PowerShell installer coming soon — use WSL + the bash installer above.
```

### From Source (any platform)

```bash
git clone git@git.mosaicstack.dev:mosaic/mosaic-stack.git ~/src/mosaic-stack
cd ~/src/mosaic-stack && bash tools/install.sh
```

The installer:

- Downloads the framework from the monorepo archive
- Installs it to `~/.config/mosaic/`
- Installs `@mosaicstack/cli` globally via npm (TUI, gateway client, wizard)
- Adds `~/.config/mosaic/bin` to your PATH
- Syncs runtime adapters and skills
- Runs a health audit
- Detects existing installs and preserves local files (SOUL.md, USER.md, etc.)

## First Run

After install, open a new terminal (or `source ~/.bashrc`) and run:

```bash
mosaic init
```

If Node.js 18+ is installed, this launches an interactive wizard with two modes:

- **Quick Start** (~2 min): agent name + communication style, sensible defaults for everything else
- **Advanced**: full customization of identity, user profile, tools, runtimes, and skills

The wizard configures three files loaded into every agent session:

- `SOUL.md` — agent identity contract (name, style, guardrails)
- `USER.md` — your user profile (name, timezone, accessibility, preferences)
- `TOOLS.md` — machine-level tool reference (git providers, credentials, CLI patterns)

It also detects installed runtimes (Claude, Codex, OpenCode, Pi), configures sequential-thinking MCP, and offers curated skill selection from 8 categories.

### Non-Interactive Mode

For CI or scripted installs:

```bash
mosaic init --non-interactive --name Jarvis --style direct --user-name Jason --timezone America/Chicago
```

All flags: `--name`, `--role`, `--style`, `--user-name`, `--pronouns`, `--timezone`, `--mosaic-home`, `--source-dir`.

### Legacy Fallback

If Node.js is unavailable, `mosaic init` falls back to the bash-based `mosaic-init` script.

## Launching Agent Sessions

```bash
mosaic pi                  # Launch Pi with full Mosaic injection (recommended)
mosaic claude              # Launch Claude Code with full Mosaic injection
mosaic codex               # Launch Codex with full Mosaic injection
mosaic opencode            # Launch OpenCode with full Mosaic injection
mosaic yolo claude         # Launch Claude in dangerous-permissions mode
mosaic yolo pi             # Launch Pi in yolo mode
```

The launcher:

1. Verifies `~/.config/mosaic` exists
2. Verifies `SOUL.md` exists (auto-runs `mosaic init` if missing)
3. Injects `AGENTS.md` into the runtime
4. Forwards all arguments to the runtime CLI

You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtime adapters will tell the agent to read `~/.config/mosaic/AGENTS.md`.

## Architecture

```
~/.config/mosaic/
├── AGENTS.md              ← THE source of truth (all standards, all runtimes)
├── SOUL.md                ← Agent identity (generated by mosaic init)
├── USER.md                ← User profile and accessibility (generated by mosaic init)
├── TOOLS.md               ← Machine-level tool reference (generated by mosaic init)
├── STANDARDS.md           ← Machine-wide standards
├── guides/                ← Operational guides (E2E delivery, PRD, docs, etc.)
├── bin/                   ← CLI tools (mosaic launcher, mosaic-init, mosaic-doctor, etc.)
├── tools/                 ← Tool suites: git, orchestrator, prdy, quality, etc.
├── runtime/               ← Runtime adapters + runtime-specific references
│   ├── claude/            ← CLAUDE.md, RUNTIME.md, settings.json, hooks
│   ├── codex/             ← instructions.md, RUNTIME.md
│   ├── opencode/          ← AGENTS.md, RUNTIME.md
│   ├── pi/                ← RUNTIME.md, mosaic-extension.ts
│   └── mcp/               ← MCP server configs
├── skills/                ← Universal skills (synced from mosaic/agent-skills)
├── skills-local/          ← Local cross-runtime skills
├── memory/                ← Persistent agent memory (preserved across upgrades)
└── templates/             ← SOUL.md template, project templates
```

### How AGENTS.md Gets Loaded

| Launch method       | Injection mechanism                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `mosaic pi`         | `--append-system-prompt` with composed runtime contract + skills + extension              |
| `mosaic claude`     | `--append-system-prompt` with composed runtime contract (`AGENTS.md` + runtime reference) |
| `mosaic codex`      | Writes composed runtime contract to `~/.codex/instructions.md` before launch              |
| `mosaic opencode`   | Writes composed runtime contract to `~/.config/opencode/AGENTS.md` before launch          |
| `claude` (direct)   | `~/.claude/CLAUDE.md` thin pointer → load AGENTS + runtime reference                      |
| `codex` (direct)    | `~/.codex/instructions.md` thin pointer → load AGENTS + runtime reference                 |
| `opencode` (direct) | `~/.config/opencode/AGENTS.md` thin pointer → load AGENTS + runtime reference             |

## Management Commands

```bash
mosaic help                # Show all commands
mosaic init                # Interactive wizard (or legacy init)
mosaic doctor              # Health audit — detect drift and missing files
mosaic sync                # Sync skills from canonical source
mosaic bootstrap <path>    # Bootstrap a repo with Mosaic standards
mosaic upgrade             # Upgrade installed Mosaic release
mosaic upgrade check       # Check upgrade status (no changes)
```

## Upgrading

Run the installer again — it handles upgrades automatically:

```bash
bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
```

Or from a local checkout:

```bash
cd ~/src/mosaic-stack && git pull && bash tools/install.sh
```

The installer preserves local `SOUL.md`, `USER.md`, `TOOLS.md`, and `memory/` by default.

### Flags

```bash
bash tools/install.sh --check       # Version check only
bash tools/install.sh --framework   # Framework only (skip npm CLI)
bash tools/install.sh --cli         # npm CLI only (skip framework)
bash tools/install.sh --ref v1.0    # Install from a specific git ref
```

## Universal Skills

The installer syncs skills from `mosaic/agent-skills` into `~/.config/mosaic/skills/`, then links each skill into runtime directories.

```bash
mosaic sync                                    # Full sync (clone + link)
~/.config/mosaic/bin/mosaic-sync-skills --link-only   # Re-link only
```

## Health Audit

```bash
mosaic doctor                                          # Standard audit
~/.config/mosaic/bin/mosaic-doctor --fail-on-warn      # Strict mode
```

## MCP Registration

### sequential-thinking MCP (Hard Requirement)

sequential-thinking MCP is required for Mosaic Stack. The installer registers it automatically.
To verify or re-register manually:

```bash
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
```

### Claude Code MCP Registration

**MCPs must be registered via `claude mcp add` — not by hand-editing `~/.claude/settings.json`.**

```bash
claude mcp add --scope user <name> -- npx -y <package>
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
claude mcp list
```