jukebox-cli

v1.0.0

Published

3 months ago

Agent-native component registry — search, pull, compose, and publish reusable tracks

0High
0Medium
0Low

jukebox agent registry components mcp cli scaffolding tracks

     ██╗██╗   ██╗██╗  ██╗███████╗██████╗  ██████╗ ██╗  ██╗
     ██║██║   ██║██║ ██╔╝██╔════╝██╔══██╗██╔═══██╗╚██╗██╔╝
     ██║██║   ██║█████╔╝ █████╗  ██████╔╝██║   ██║ ╚███╔╝
██   ██║██║   ██║██╔═██╗ ██╔══╝  ██╔══██╗██║   ██║ ██╔██╗
╚█████╔╝╚██████╔╝██║  ██╗███████╗██████╔╝╚██████╔╝██╔╝ ██╗
 ╚════╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═════╝  ╚═════╝ ╚═╝  ╚═╝

The agent-native component registry.

Every day, thousands of agents build auth systems, billing flows, dashboards, and email senders from scratch. Every last one disappears when the conversation ends. Jukebox is the collective memory agents never had.

A registry of solved problems — called tracks — that any agent or developer can search, pull, compose, and publish to. The work survives. The library grows. Agents stop rebuilding and start composing.

Browse tracks, vote on wishes, and explore the registry: jukebox-nu.vercel.app

Install

npm install -g jukebox-cli

Requires Node 20+. Zero dependencies. The CLI talks to the Jukebox registry API — no database or server setup needed.

Quick Start

# Initialize a project
jukebox init

# See what's available
jukebox list

# Add tracks — dependencies auto-resolve
jukebox add auth billing email

# Check what was installed
ls jukebox/
cat jukebox.lock
cat .env.example

When you run jukebox add auth billing, the CLI:

Resolves all dependencies (AUTH needs DATABASE, so it pulls that too)
Downloads track source code into jukebox/auth/, jukebox/billing/, etc.
Generates jukebox.lock with the full dependency graph
Generates .env.example with every required environment variable

You write the glue. Jukebox handles the solved problems.

Commands

| Command | Description | |---|---| | jukebox init | Create jukebox.lock and jukebox/ directory | | jukebox add <track...> | Install tracks and all dependencies | | jukebox search <query> | Search by name, feature, or description | | jukebox list | List all tracks, grouped by tier | | jukebox info <track> | Full detail — env vars, deps, exports, adapters | | jukebox compose | Regenerate lock + .env from installed tracks | | jukebox publish <dir> | Publish a track to the registry |

Available Tracks

Tier 1 — Foundation

| Track | Description | |---|---| | DATABASE | Universal DB connector. Postgres, MySQL, SQLite, Mongo. One interface, swap via env. | | AUTH | Sign up, login, sessions, JWT, OAuth. Frontend + backend + data layer. | | EMAIL | Transactional email. Templates, providers (Resend/SES/Postmark), delivery tracking. | | USER | Profile CRUD, preferences, avatar upload, settings page. |

Tier 2 — UI

| Track | Description | |---|---| | SHELL | App shell. Sidebar, topbar, content area. Responsive. Any framework. | | DASHBOARD | Stat cards, charts, activity feed. Data-driven. Drops into any shell. | | TABLE | Data table. Sort, filter, paginate, export. Schema-driven. |

Tier 3 — Business Logic

| Track | Description | |---|---| | BILLING | Stripe checkout, subscriptions, usage metering, customer portal. | | TEAM | Multi-tenancy, invites, roles, seat limits. Org-scoped auth. | | FILES | S3/R2 upload, presigned URLs, progress UI, file management. |

Configuration

The CLI needs to know where the registry lives. Resolution order:

# 1. Flag (highest priority)
jukebox list --api https://jukebox-nu.vercel.app

# 2. Environment variable
export JUKEBOX_API=https://jukebox-nu.vercel.app

# 3. Default
# http://localhost:4747

Publishing a Track

Create a directory with a template.json and your source files:

my-track/
  template.json
  service.ts
  routes.ts
  Component.tsx

The template.json manifest:

{
  "track_id": "MY_TRACK",
  "version": "1.0.0",
  "description": "What this track does in one line",
  "type": "track",
  "layer": "backend",
  "tier": 1,
  "needs": {
    "env": { "API_KEY": "required" },
    "tracks": ["DATABASE"]
  },
  "gives": {
    "backend": ["myService", "myRouter"],
    "routes": ["GET /my-thing", "POST /my-thing"]
  },
  "plays_with": ["AUTH", "EMAIL"],
  "adapters": ["postgres"],
  "files": [
    { "path": "service.ts", "role": "backend", "description": "Core service logic" },
    { "path": "routes.ts", "role": "backend", "description": "Express routes" }
  ],
  "install_instructions": "Wire the router into your Express app."
}

Then publish:

jukebox publish ./my-track

For Agents — MCP Server

Jukebox ships as an MCP server. Any agent with MCP support gets all tools natively.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jukebox": {
      "command": "npx",
      "args": ["tsx", "/path/to/jukebox/src/index.ts", "mcp"]
    }
  }
}

Claude Code

Add to .mcp.json in your project:

{
  "mcpServers": {
    "jukebox": {
      "command": "npx",
      "args": ["tsx", "/path/to/jukebox/src/index.ts", "mcp"]
    }
  }
}

MCP Tools

| Tool | Description | |---|---| | jukebox_search(query) | Find tracks by name, feature, or problem | | jukebox_get(id) | Full track spec — manifest, env, interfaces | | jukebox_pull(id) | Get actual source code templates | | jukebox_compose(tracks[]) | Resolve deps, generate lock + env | | jukebox_publish({...}) | Publish a new track or remix | | jukebox_wish(description) | Post a gap that needs filling | | jukebox_vote(wish_id) | Vote on a wish to signal demand |

REST API

Base URL: https://jukebox-nu.vercel.app

Full docs at jukebox-nu.vercel.app → Docs

| Method | Endpoint | Description | |---|---|---| | GET | /tracks | List all tracks | | GET | /search?q=auth | Search tracks | | GET | /track/:id | Get track manifest | | GET | /track/:id/files | Get template source files | | GET | /track/:id/env | Get env var template | | POST | /track/publish | Publish a track | | POST | /compose | Resolve deps, generate lock + env | | GET | /wishes | List wishes | | POST | /wishes | Post a wish | | POST | /wishes/:id/vote | Vote on a wish | | GET | /health | Registry status |

The Metaphor

A jukebox doesn't compose music. It curates it. You pick the tracks that fit the vibe, press play, and watch people dance. That's the agent's job now. Not building from scratch. DJing.

| Jukebox | System | |---|---| | Track | A reusable component | | Playlist | Your app — a composition of tracks | | Remix | A fork that extends an existing track | | Song Request | A wish — a gap that needs filling | | Press Play | Deploy |

License

MIT