Install Mosaic

Mosaic keeps a background-synchronized local replica of team coding-agent sessions at ~/.mosaic. This page is the complete public setup and recovery guide — you do not need the GitHub repository.

Requirements

  • macOS 14 or newer on Apple Silicon or Intel
  • A sign-in method: GitHub, Google, work email, or a team invitation link
  • Internet access during setup and sync

Homebrew is optional when you use the shell installer. Mosaic does not require Node.js, npm, rclone, an MCP server, or a preinstalled agent skill — required components are bundled or installed automatically.

Install

For a person at a terminal, pick one interactive path. Both end in mosaic install, which opens the Ink setup, authorizes this Mac, starts local Drive preparation, and installs agent guidance.

Homebrew

Installs the CLI from the Emergent tap, then chains mosaic install. Homebrew cannot finish setup by itself.

Homebrew (interactive)$ brew install emergent-inc/tap/mosaic && mosaic install

Shell installer

No Homebrew needed. The bootstrap script downloads the CLI and ends by running mosaic install itself.

Shell installer (interactive)$ curl -fsSL https://raw.githubusercontent.com/emergent-inc/homebrew-tap/main/install.sh | sh

What mosaic install does

  1. Opens browser authorization (GitHub, Google, or email). A separate mosaic login is only needed later to reauthenticate.
  2. Lets you create, join, or select the active Mosaic team.
  3. Reviews detected coding-agent session sources. Detected sources are enabled by default.
  4. Registers the background LaunchAgent (com.ocean.daemon) and starts syncing.
  5. Builds a completed local replica in the background and exposes it at ~/.mosaic without showing partial data.
  6. Prompts before installing the Mosaic skill into supported coding agents' personal skill directories.

If macOS blocks background activity, Mosaic opens System Settings → General → Login Items & Extensions so you can allow it. You do not manually add a Login Item.

Setup can complete while the first local replica is preparing in the background. Check Drive status for ready, syncing, or stale.

Coding agents

Give an agent this page (/install) as the only entry point. Agents and automation must use mosaic install --yes so setup cannot wait on terminal prompts. With Homebrew:

brew install emergent-inc/tap/mosaic && mosaic install --yes

Or use the agent-safe bootstrap without Homebrew:

bash -o pipefail -c 'curl -fsSL https://raw.githubusercontent.com/emergent-inc/homebrew-tap/main/install.sh | OCEAN_INSTALL_ONLY=1 sh' && "$HOME/.local/bin/mosaic" install --yes

Browser authorization and any required macOS background-activity approval still cannot be bypassed.

Interactive setup prompts before installing skills; mosaic install --yes accepts the default. To install, repair, or update guidance later:

mosaic skills install

Optional agent ids narrow the install, for example mosaic skills install cursor claude-code. Mosaic never overwrites a conflicting user-owned skill.

Mosaic does not install or modify coding agents, hooks, MCP servers, or editor extensions. It only adds instruction-only skill files.

Verify the setup

mosaic doctor --json
mosaic status --json
open ~/.mosaic

Healthy means:

  • doctor reports ok: true and the replica is ready or syncing
  • ~/.mosaic opens and shows the active team's People tree
  • status shows the expected team and enabled agents

Recovery

If setup becomes unhealthy, start with diagnosis, then repair:

mosaic doctor --json
mosaic refresh

mosaic refresh reconciles authentication, the background service, and local replica without deleting native agent sessions. mosaic repair is an alias for the same command.

Common trip-ups:

  • Homebrew installed the binary but setup never ran — run mosaic install
  • Browser authorization was skipped or expired — run mosaic login or mosaic refresh
  • macOS blocked background activity — allow Ocean (Mosaic)in Login Items & Extensions, then mosaic refresh
  • Drive not ready yet — wait a short time after install, then re-check mosaic doctor --json
  • Agent guidance missing — run mosaic skills install

For a clean reinstall on the same Mac, stop sync and remove managed services first:

mosaic uninstall
brew reinstall emergent-inc/tap/mosaic   # if you use Homebrew
mosaic install

Uninstall removes the LaunchAgent, local replica presentation, and Keychain refresh credential. It preserves durable native session state and already uploaded team data so a reinstall can recover.

CLI command reference

Paths default to the current folder where noted. Commands that change backup scope affect only this Mac.

Setup and health

mosaicOpen the installer and management TUI
mosaic install [--yes] [--team <slug>]Authorize this Mac, select a team, and start Mosaic
mosaic login [--agent]Reauthorize a person or claim an agent invitation
mosaic status [--json]Show the active team, agents, scope, and sync health
mosaic doctor [--json]Diagnose setup and suggest repairs

Backup scope

mosaic scope [list]Show whether this Mac backs up all sessions or selected folders
mosaic scope selected [path]Switch to selected-folder backup and include this folder
mosaic scope add [path]Include another recursive folder
mosaic scope remove [path]Stop backing up a selected folder and safely clean known objects
mosaic scope allReturn this Mac to backing up every detected session

Sessions and teammates

mosaic team listList teams available to this installation
mosaic team members [--json]List active-team members and their @handles
mosaic team use <team-id-or-slug>Switch the active team and prepare its local replica
mosaic fork <session-reference-or-id> [--cwd <path>] [--no-launch]Continue a shared session in its native coding agent
mosaic handoff <@teammate> [session-reference-or-id] [--provider <agent-id>] [--cwd <path>] [--json]Assign a session and notify a teammate

Drive and sync

mosaic ls [path]List session paths directly from remote storage
mosaic cat <session-path>Write one remote session artifact to stdout
mosaic pausePause session shipping on this Mac
mosaic resumeResume session shipping

Maintenance

mosaic update [--check] [--json]Check for or install the latest stable release
mosaic refreshReconcile authentication, background service, and local replica
mosaic repairAlias for mosaic refresh
mosaic skills install [agent-id ...]Install or reconcile Mosaic guidance for selected agents
mosaic uninstallRemove Mosaic services while preserving local sessions
mosaic --versionPrint the installed Mosaic version

What Mosaic places on the Mac

  • CLI — Homebrew prefix, or ~/.local/bin/mosaic for the shell installer
  • Background service — ~/Library/LaunchAgents/com.ocean.daemon.plist
  • App state — ~/Library/Application Support/Ocean
  • Local team replica — ~/.mosaic (read-only; legacy ~/.ocean remains an alias)
  • Agent skills— each supported agent's personal skills directory

Mosaic runs while that user is logged in. It does not run before login, and it does not collect product telemetry.