BeatOS

The operating system for beat producers.

A local-first library for every beat on your drive — catalog it once, run it as a native desktop app or in your browser, then ship it to every platform with an AI co-pilot doing the metadata grind for you.

A working beat producer ends up with hundreds of WAV/MP3 files on disk, two versions of each (tagged + untagged), cover art that isn't always next to the file, and a different metadata vocabulary for every platform:

• NetEase / QQ Music / Suno / BeatStars / YouTube — different genre trees, different mood tags, different description lengths, different price models.
• A track that's "Trap" on one site is "Hip Hop · 暗黑" on another, "Aggressive Lo-Fi" on a third, "未分类" on a fourth.
• Every release means re-typing the same data in a different costume. Multiply by 50 unfinished beats and 4 platforms — that's 200 metadata blocks to maintain by hand. Which is why most producers just don't publish.

BeatOS fixes this by keeping one canonical catalog locally, then letting either you or an AI agent translate it into the per-platform metadata block on demand.

BeatOS ships as a native desktop app (Electron) and a browser app (a local web SPA served by the same Python sidecar). One React codebase builds both, so the two stay in lockstep: Electron-only capabilities (native file dialogs, Finder/Explorer integration, drag-out) route through a thin platform seam with a same-origin web implementation behind it.

Both are local-first and offline — the browser app talks only to 127.0.0.1. (Remote/LAN access and a mobile layout are on the roadmap.)

BeatOS is the first beat library built for the AI-agent era. The MCP surface is not a side feature — it's how publishing is going to scale to 10 platforms without manual labor.

Verified clients: Claude Code CLI · Claude Desktop · any MCP client speaking stdio JSON-RPC.

BeatOS registered as a Desktop MCP connector in Claude Desktop — read-only tools auto-allowed, writes gated behind approval.

Tools shipping today (24 in the free build; the Pro build adds publish_track, publish_status, list_publish_platforms, publish_session_status + list_publish_jobs for 29):

Why two-phase commit? Every write tool returns a token (preview only) — nothing touches the database. The token surfaces in the Agent Actions panel in BeatOS; you review the diff, then confirm. The agent calls await_approval to learn the outcome. By default an AI can never silently mutate your catalog, batch-edit your producer credits, or trash a track without you signing off — unless you deliberately switch the permission setting to auto-approve (or lock it to read-only).

Why batches? A folder-import of 50 tracks × 2 audio assets would otherwise be 100 approval clicks. create_tracks (≤100), attach_assets (≤500), detach_assets (≤500) all batch — one token, one click, atomic rollback if any file vanishes mid-approve.

Example flow (driven by Claude Code from your terminal):

You:    "Tag every beat above 140 BPM that has no genre with 'Trap' or 'Drill'
         based on the cover art and title. Show me the diff before applying."

Claude: [calls list_tracks(bpm_min=140) → 12 tracks]
        [reads metadata, drafts a patch]
        [calls update_tracks(items=[...]) → returns token abc123]

You:    [opens BeatOS Approvals panel, sees 12 proposed edits with rationale]
        [reviews 3, rejects 1, approves the batch]

Claude: [await_approval → status=approved, applies, reports back]

The same pattern drives on-demand per-platform metadata export today, and will drive publish drafts (Pro) and self-corpus RAG drafts (v0.3+).

Packaged desktop installers will arrive at v0.1.0 together with the first publish adapter. Until then, run from source — see Develop. The browser front end needs no packaging: make web and open a tab.

Targets: macOS 12+ · Windows 10+ (desktop) · any modern browser (web). Linux works for development and the web front end, but isn't a supported desktop install target.

Prerequisites

• Node ≥22 LTS
• Python 3.11.x
• uv — brew install uv (macOS) or pipx install uv

Setup

make sync                              # resolve Python workspace
cd apps/desktop && npm install

Pro build (publishing). Publishing is a Pro feature in the private packages/pro/ submodule. With access to it: git submodule update --init packages/pro, then uv pip install -e packages/pro/beatos-publish --no-deps + uv pip install "patchright>=1.40", then run with make dev-pro (desktop) or make web-pro (browser) — each reinstalls the engine after uv sync, which the free make dev / make web prune. Full steps in packages/pro-mount-notes.md. Without it, the free build runs normally and greys out the publish entry.

make dev                               # desktop: Electron + sidecar (or: npm run dev:fresh)
make web                               # browser: build the SPA + serve it from the sidecar, open a tab
npm run logs:tail                      # follow main.log + sidecar.jsonl  (from apps/desktop)

No terminal? Double-click start-beatos.bat (Windows) or start-beatos.command (macOS) at the repo root — it checks/installs the prerequisites, then launches the browser or desktop app.

The MCP server lives at packages/beatos-mcp and speaks stdio. Add to your MCP client config:

{
  "mcpServers": {
    "beatos": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/beatos", "beatos-mcp"]
    }
  }
}

Then list_tracks and friends will be available as tools inside Claude.

cd apps/desktop
npx vitest run                         # renderer + main (Vitest)
npm run build && npm run smoke         # desktop end-to-end (Playwright _electron)
npm run build:web && npm run smoke:web # browser end-to-end (Playwright chromium)

uv run pytest packages/                # Python sidecar (core + http + mcp)

Electron 39 · React 19 · Vite · Tailwind · Radix UI · Zustand · TanStack Virtual · dnd-kit · Tone.js Python 3.11 · FastAPI · aiosqlite · structlog · mcp (FastMCP) · librosa / essentia (optional) · Playwright SQLite · Pydantic v2

The single React renderer builds to two targets — Electron (electron-vite) and a browser SPA (vite.config.web.ts) the FastAPI sidecar serves at /.

apps/desktop/              Electron shell + React renderer (also builds the browser SPA)
packages/
  beatos-core/             Pure Python business logic (no web/RPC deps)
  beatos-http/             FastAPI facade — serves the renderer API, /api/fs, and the web SPA
  beatos-mcp/              stdio MCP server for AI agents
  beatos-platforms/        Per-platform vocab maps
  pro/                     Private submodule — Pro features (platform publishing); absent in the free build
screenshots/               README assets

Currently in the dogfood phase — UI/UX patches land as 0.0.X.Y releases. The catalog, the AI/MCP surface, on-demand metadata export, and the desktop + browser front ends are shipped; platform publishing is a Pro module. Next up: the first packaged installer + publish adapter (NetEase Cloudmusic), and — for the web front end — remote/LAN access and a mobile layout.

Full plan: ROADMAP.md · Shipped history: CHANGELOG.md.

Apache License 2.0 — see LICENSE and NOTICE.

Copyright 2026 Scott Huang (averatec0773).