Mosaic Agent Framework

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

One config, every runtime, same standards.

Quick Install

Mac / Linux

curl -sL https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.sh | sh

Windows (PowerShell)

irm https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.ps1 | iex

From Source (any platform)

git clone https://git.mosaicstack.dev/mosaic/bootstrap.git ~/src/mosaic-bootstrap
bash ~/src/mosaic-bootstrap/install.sh

The installer will:

• Install the framework to ~/.config/mosaic/
• Add ~/.config/mosaic/bin to your PATH
• Sync runtime adapters and skills
• Run a health audit
• Prompt you to run mosaic init to set up your agent identity

First Run

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

mosaic init

This generates ~/.config/mosaic/SOUL.md — your agent identity contract. It's loaded into every session regardless of runtime.

Launching Agent Sessions

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

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                ← User identity (generated by mosaic init)
├── STANDARDS.md           ← Machine-wide standards
├── bin/                   ← CLI tools (mosaic, mosaic-init, mosaic-doctor, etc.)
├── guides/                ← Operational guides
├── rails/                 ← Quality rails, git scripts, portainer scripts
├── runtime/               ← Thin runtime adapters (fallback for direct launches)
│   ├── claude/CLAUDE.md
│   ├── opencode/AGENTS.md
│   └── codex/instructions.md
├── skills/                ← Universal skills (synced from mosaic/agent-skills)
├── skills-local/          ← Local cross-runtime skills
└── templates/             ← SOUL.md template, project templates

How AGENTS.md Gets Loaded

Launch method	Injection mechanism
mosaic claude	--append-system-prompt with AGENTS.md content
mosaic codex	Copies AGENTS.md to ~/.codex/instructions.md before launch
mosaic opencode	Copies AGENTS.md to ~/.config/opencode/AGENTS.md before launch
claude (direct)	~/.claude/CLAUDE.md thin pointer → "READ AGENTS.md"
codex (direct)	~/.codex/instructions.md thin pointer → "READ AGENTS.md"
opencode (direct)	~/.config/opencode/AGENTS.md thin pointer → "READ AGENTS.md"

Management Commands

mosaic help                # Show all commands
mosaic init                # Generate SOUL.md (agent identity)
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 [path]      # Clean up stale per-project files (see below)
mosaic upgrade --all       # Upgrade all projects in ~/src
mosaic upgrade --dry-run   # Preview without changes

Upgrading Projects

After centralizing AGENTS.md and SOUL.md, existing projects may have stale files:

# Preview what would change across all projects
mosaic upgrade --all --dry-run

# Apply to all projects
mosaic upgrade --all

# Apply to a specific project
mosaic upgrade ~/src/my-project

What it does per project:

File	Action
SOUL.md	Removed — now global at ~/.config/mosaic/SOUL.md
CLAUDE.md	Replaced with thin pointer to global AGENTS.md
AGENTS.md	Stale load-order sections stripped; project content preserved

Backups (.mosaic-bak) are created before any modification.

Universal Skills

The installer syncs skills from mosaic/agent-skills into ~/.config/mosaic/skills/, then links each skill into runtime directories (~/.claude/skills, ~/.codex/skills, ~/.config/opencode/skills).

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

Runtime Compatibility

The installer pushes thin runtime adapters as regular files (not symlinks):

• ~/.claude/CLAUDE.md — pointer to ~/.config/mosaic/AGENTS.md
• ~/.claude/settings.json, hooks-config.json, context7-integration.md
• ~/.config/opencode/AGENTS.md — pointer to ~/.config/mosaic/AGENTS.md
• ~/.codex/instructions.md — pointer to ~/.config/mosaic/AGENTS.md

Re-sync manually:

~/.config/mosaic/bin/mosaic-link-runtime-assets

Bootstrap Any Repo

Attach any repository to the Mosaic standards layer:

mosaic bootstrap /path/to/repo

This creates .mosaic/, scripts/agent/, and an AGENTS.md if missing.

Quality Rails

Apply and verify quality templates:

~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/repo

Templates: typescript-node, typescript-nextjs, monorepo

Health Audit

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

Re-installing / Updating

Pull the latest and re-run the installer:

cd ~/src/mosaic-bootstrap && git pull && bash install.sh

Or use the one-liner again — it always pulls the latest:

curl -sL https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.sh | sh