mosaic-queue

Valkey/Redis-backed task queue with:

• Atomic task lifecycle operations (claim, release, heartbeat, complete, fail)
• CLI commands for queue management
• MCP server tools for agent integrations

Requirements

• Node.js >=20
• pnpm 10.x
• Valkey/Redis URL in one of:
  • VALKEY_URL
  • REDIS_URL

No default Redis URL is hardcoded. Startup fails loudly when neither env var exists.

Install

pnpm install
pnpm build

CLI Usage

The package ships a mosaic binary.

mosaic queue create <project> <mission> <taskId> --title "..." [--priority high] [--lane coding]
mosaic queue list [--project X] [--mission Y] [--status pending]
mosaic queue show <taskId>
mosaic queue claim <taskId> --agent <agentId> --ttl 3600
mosaic queue release <taskId> [--agent <agentId>]
mosaic queue complete <taskId> [--agent <agentId>] [--summary "..."]

Example:

export VALKEY_URL="redis://localhost:6379"
mosaic queue create queue phase1 MQ-001 --title "Implement core queue"
mosaic queue claim MQ-001 --agent codex --ttl 3600

MCP Server

The package also ships a mosaic-queue-mcp binary exposing:

• queue_list
• queue_get
• queue_claim
• queue_heartbeat
• queue_release
• queue_complete
• queue_fail
• queue_status

Run over stdio:

export VALKEY_URL="redis://localhost:6379"
mosaic-queue-mcp

Development

pnpm lint
pnpm test
pnpm build

Publish Prep

packages/queue/package.json includes:

• bin entries for mosaic and mosaic-queue-mcp
• exports + types for ESM package consumption
• prepublishOnly quality gate (lint, test, build)
• publishConfig.access = public