116b91d2ae
The published @mosaic/config@0.0.1 on the Gitea registry is the
stale tooling-configs package (tsconfig/eslint/prettier) with only
subpath exports. When the package was repurposed in 04a80fb9 as the
runtime config loader, its version was never bumped, so consumers
that pull from the registry still get the old tarball.
This caused `mosaic gateway install` to fail with
ERR_PACKAGE_PATH_NOT_EXPORTED when gateway imported loadConfig from
@mosaic/config at runtime.
- Bump @mosaic/config to 0.0.2 so CI publishes the runtime variant
- Bump @mosaic/gateway to 0.0.5 to republish with the fixed dep
(0.1.0 was an unintended semver jump; deleted from registry to
restore 0.0.x lineage)
- Bump @mosaic/mosaic to 0.0.19 so the CLI ships with the fixed
transitive dep resolution
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Mosaic Stack
Self-hosted, multi-user AI agent platform. One config, every runtime, same standards.
Mosaic gives you a unified launcher for Claude Code, Codex, OpenCode, and Pi — injecting consistent system prompts, guardrails, skills, and mission context into every session. A NestJS gateway provides the API surface, a Next.js dashboard gives you the UI, and a plugin system connects Discord, Telegram, and more.
Quick Install
bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
This installs both components:
| Component | What | Where |
|---|---|---|
| Framework | Bash launcher, guides, runtime configs, tools, skills | ~/.config/mosaic/ |
| @mosaic/cli | TUI, gateway client, wizard, auto-updater | ~/.npm-global/bin/ |
After install, set up your agent identity:
mosaic init # Interactive wizard
Requirements
- Node.js ≥ 20
- npm (for global @mosaic/cli install)
- One or more runtimes: Claude Code, Codex, OpenCode, or Pi
Usage
Launching Agent Sessions
mosaic pi # Launch Pi with Mosaic injection
mosaic claude # Launch Claude Code with Mosaic injection
mosaic codex # Launch Codex with Mosaic injection
mosaic opencode # Launch OpenCode with Mosaic injection
mosaic yolo claude # Claude with dangerous-permissions mode
mosaic yolo pi # Pi in yolo mode
The launcher verifies your config, checks for SOUL.md, injects your AGENTS.md standards into the runtime, and forwards all arguments.
TUI & Gateway
mosaic tui # Interactive TUI connected to the gateway
mosaic login # Authenticate with a gateway instance
mosaic sessions list # List active agent sessions
Management
mosaic doctor # Health audit — detect drift and missing files
mosaic sync # Sync skills from canonical source
mosaic update # Check for and install CLI updates
mosaic wizard # Full guided setup wizard
mosaic bootstrap <path> # Bootstrap a repo with Mosaic standards
mosaic coord init # Initialize a new orchestration mission
mosaic prdy init # Create a PRD via guided session
Development
Prerequisites
- Node.js ≥ 20
- pnpm 10.6+
- Docker & Docker Compose
Setup
git clone git@git.mosaicstack.dev:mosaic/mosaic-stack.git
cd mosaic-stack
# Start infrastructure (Postgres, Valkey, Jaeger)
docker compose up -d
# Install dependencies
pnpm install
# Run migrations
pnpm --filter @mosaic/db run db:migrate
# Start all services in dev mode
pnpm dev
Infrastructure
Docker Compose provides:
| Service | Port | Purpose |
|---|---|---|
| PostgreSQL (pgvector) | 5433 | Primary database |
| Valkey | 6380 | Task queue + caching |
| Jaeger | 16686 | Distributed tracing UI |
| OTEL Collector | 4317/4318 | Telemetry ingestion |
Quality Gates
pnpm typecheck # TypeScript type checking (all packages)
pnpm lint # ESLint (all packages)
pnpm test # Vitest (all packages)
pnpm format:check # Prettier check
pnpm format # Prettier auto-fix
CI
Woodpecker CI runs on every push:
pnpm install --frozen-lockfile- Database migration against a fresh Postgres
pnpm test(Turbo-orchestrated across all packages)
npm packages are published to the Gitea package registry on main merges.
Architecture
mosaic-stack/
├── apps/
│ ├── gateway/ NestJS API + WebSocket hub (Fastify, Socket.IO, OTEL)
│ └── web/ Next.js dashboard (React 19, Tailwind)
├── packages/
│ ├── cli/ Mosaic CLI — TUI, gateway client, wizard
│ ├── mosaic/ Framework — wizard, runtime detection, update checker
│ ├── types/ Shared TypeScript contracts (Socket.IO typed events)
│ ├── db/ Drizzle ORM schema + migrations (pgvector)
│ ├── auth/ BetterAuth configuration
│ ├── brain/ Data layer (PG-backed)
│ ├── queue/ Valkey task queue + MCP
│ ├── coord/ Mission coordination
│ ├── forge/ Multi-stage AI pipeline (intake → board → plan → code → review)
│ ├── macp/ MACP protocol — credential resolution, gate runner, events
│ ├── agent/ Agent session management
│ ├── memory/ Agent memory layer
│ ├── log/ Structured logging
│ ├── prdy/ PRD creation and validation
│ ├── quality-rails/ Quality templates (TypeScript, Next.js, monorepo)
│ └── design-tokens/ Shared design tokens
├── plugins/
│ ├── discord/ Discord channel plugin (discord.js)
│ ├── telegram/ Telegram channel plugin (Telegraf)
│ ├── macp/ OpenClaw MACP runtime plugin
│ └── mosaic-framework/ OpenClaw framework injection plugin
├── tools/
│ └── install.sh Unified installer (framework + npm CLI)
├── scripts/agent/ Agent session lifecycle scripts
├── docker-compose.yml Dev infrastructure
└── .woodpecker/ CI pipeline configs
Key Design Decisions
- Gateway is the single API surface — all clients (TUI, web, Discord, Telegram) connect through it
- ESM everywhere —
"type": "module",.jsextensions in imports, NodeNext resolution - Socket.IO typed events — defined in
@mosaic/types, enforced at compile time - OTEL auto-instrumentation — loads before NestJS bootstrap
- Explicit
@Inject()decorators — required since tsx/esbuild doesn't emit decorator metadata
Framework (~/.config/mosaic/)
The framework is the bash-based standards layer installed to every developer machine:
~/.config/mosaic/
├── AGENTS.md ← Central standards (loaded into every runtime)
├── SOUL.md ← Agent identity (name, style, guardrails)
├── USER.md ← User profile (name, timezone, preferences)
├── TOOLS.md ← Machine-level tool reference
├── bin/mosaic ← Unified launcher (claude, codex, opencode, pi, yolo)
├── guides/ ← E2E delivery, orchestrator protocol, PRD, etc.
├── runtime/ ← Per-runtime configs (claude/, codex/, opencode/, pi/)
├── skills/ ← Universal skills (synced from agent-skills repo)
├── tools/ ← Tool suites (orchestrator, git, quality, prdy, etc.)
└── memory/ ← Persistent agent memory (preserved across upgrades)
Forge Pipeline
Forge is a multi-stage AI pipeline for autonomous feature delivery:
Intake → Discovery → Board Review → Planning (3 stages) → Coding → Review → Remediation → Test → Deploy
Each stage has a dispatch mode (exec for research/review, yolo for coding), quality gates, and timeouts. The board review uses multiple AI personas (CEO, CTO, CFO, COO + specialists) to evaluate briefs before committing resources.
Upgrading
Run the installer again — it handles upgrades automatically:
bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
Or use the CLI:
mosaic update # Check + install CLI updates
mosaic update --check # Check only, don't install
The CLI also performs a background update check on every invocation (cached for 1 hour).
Installer Flags
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
Contributing
# Create a feature branch
git checkout -b feat/my-feature
# Make changes, then verify
pnpm typecheck && pnpm lint && pnpm test && pnpm format:check
# Commit (husky runs lint-staged automatically)
git commit -m "feat: description of change"
# Push and create PR
git push -u origin feat/my-feature
DTOs go in *.dto.ts files at module boundaries. Scratchpads (docs/scratchpads/) are mandatory for non-trivial tasks. See AGENTS.md for the full standards reference.
License
Proprietary — all rights reserved.