feat: unify mosaic CLI — single binary, no PATH conflict #351

2026-04-03T00:24:11Z

jason.woltje commented

2026-04-03 00:24:11 +00:00

Problem

Two different binaries both named mosaic:

~/.config/mosaic/bin/mosaic (bash framework launcher)
~/.npm-global/bin/mosaic (npm CLI)

Whichever appears first on PATH shadows the other. Users had to carefully order PATH entries.

Solution

One mosaic binary — the npm CLI (@mosaic/cli) is the single entrypoint.

Runtime commands (claude, codex, opencode, pi, yolo) and framework management commands (init, doctor, sync, seq, bootstrap, coord, upgrade) delegate to the renamed mosaic-launch bash script via execFileSync at its absolute path (~/.config/mosaic/bin/mosaic-launch).

Users only need ~/.npm-global/bin on PATH.

Changes

File	Change
`packages/mosaic/framework/bin/mosaic` → `mosaic-launch`	Renamed
`packages/cli/src/cli.ts`	Added launcher delegation for all runtime + management commands
`tools/install.sh`	Removed framework PATH requirement, auto-cleans old `mosaic` binary, simplified summary
`packages/mosaic/framework/install.sh`	Added `sources` to preserved paths (fixes rsync noise about agent-skills)
`packages/mosaic/framework/tools/orchestrator/session-run.sh`	Updated references to `mosaic-launch`

After this change

$ mosaic --help
Usage: mosaic [options] [command]

Mosaic Stack CLI

Options:
  -V, --version   output the version number
  -h, --help      display help for command

Commands:
  claude          Launch Claude Code with Mosaic injection
  codex           Launch Codex with Mosaic injection
  opencode        Launch OpenCode with Mosaic injection
  pi              Launch Pi with Mosaic injection
  yolo <runtime>  Launch a runtime in dangerous-permissions mode
  init            Generate SOUL.md (agent identity contract)
  doctor          Health audit
  sync            Sync skills from canonical source
  login           Sign in to a Mosaic gateway
  tui             Launch interactive TUI
  update          Check for and install CLI updates
  wizard          Run the Mosaic installation wizard
  ...

All from a single mosaic binary.

## Problem Two different binaries both named `mosaic`: - `~/.config/mosaic/bin/mosaic` (bash framework launcher) - `~/.npm-global/bin/mosaic` (npm CLI) Whichever appears first on PATH shadows the other. Users had to carefully order PATH entries. ## Solution **One `mosaic` binary** — the npm CLI (`@mosaic/cli`) is the single entrypoint. Runtime commands (`claude`, `codex`, `opencode`, `pi`, `yolo`) and framework management commands (`init`, `doctor`, `sync`, `seq`, `bootstrap`, `coord`, `upgrade`) delegate to the renamed `mosaic-launch` bash script via `execFileSync` at its absolute path (`~/.config/mosaic/bin/mosaic-launch`). Users only need `~/.npm-global/bin` on PATH. ## Changes | File | Change | |---|---| | `packages/mosaic/framework/bin/mosaic` → `mosaic-launch` | Renamed | | `packages/cli/src/cli.ts` | Added launcher delegation for all runtime + management commands | | `tools/install.sh` | Removed framework PATH requirement, auto-cleans old `mosaic` binary, simplified summary | | `packages/mosaic/framework/install.sh` | Added `sources` to preserved paths (fixes rsync noise about agent-skills) | | `packages/mosaic/framework/tools/orchestrator/session-run.sh` | Updated references to `mosaic-launch` | ## After this change ``` $ mosaic --help Usage: mosaic [options] [command] Mosaic Stack CLI Options: -V, --version output the version number -h, --help display help for command Commands: claude Launch Claude Code with Mosaic injection codex Launch Codex with Mosaic injection opencode Launch OpenCode with Mosaic injection pi Launch Pi with Mosaic injection yolo <runtime> Launch a runtime in dangerous-permissions mode init Generate SOUL.md (agent identity contract) doctor Health audit sync Sync skills from canonical source login Sign in to a Mosaic gateway tui Launch interactive TUI update Check for and install CLI updates wizard Run the Mosaic installation wizard ... ``` All from a single `mosaic` binary.

jason.woltje force-pushed feat/unify-mosaic-cli from 0a76afb7f2 to 2b99908de4

2026-04-03 00:30:29 +00:00

Compare

jason.woltje force-pushed feat/unify-mosaic-cli from 2b99908de4 to 15830e2f2a

2026-04-03 00:37:20 +00:00

Compare

jason.woltje merged commit 8efbaf100e into main

2026-04-03 00:41:07 +00:00

jason.woltje referenced this issue from a commit

2026-04-03 00:41:08 +00:00

Merge pull request 'feat: unify mosaic CLI — single binary, no PATH conflict' (#351) from feat/unify-mosaic-cli into main

jason.woltje referenced this issue from a commit