DJ Claude

     _  _                _                 _
  __| |(_)        ___  | |  __ _  _   _  __| |  ___
 / _` || |       / __| | | / _` || | | |/ _` | / _ \
| (_| || |  _   | (__  | || (_| || |_| | (_| ||  __/
 \__,_|| | (_)   \___| |_| \__,_| \__,_|\__,_| \___|
      _/ |
     |__/

DJ Claude

面向 AI Agent 的现场音乐引擎。

---

关于

DJ Claude 是唯一支持多 Agent 协作的音乐 MCP 服务。多个 AI Agent 通过 HTTP 连接并实时即兴合奏——一个添加鼓点，另一个叠加贝斯，第三个加入旋律——所有内容都会自动编排。它可以在终端、浏览器中运行，也可以作为带斜杠命令的 Claude Code 插件使用。无需浏览器标签页、API 密钥或外部服务。

DJ Claude 在底层使用 Strudel——一个音乐实时编程环境——实时生成并播放模式。它提供 20 个 MCP 工具、3 个资源、指挥模式、混音快照、22 个预设和 8 种氛围。Agent 可以在工作时为你、自己和彼此创作音乐。

为什么选择 DJ Claude？

• 多 Agent 即兴合奏——首个支持多个 Agent 通过 HTTP 连接并实时共同创作音乐的音乐 MCP；每个 Agent 添加的音轨都会自动编排
• 零依赖——无需浏览器标签页、API 密钥或外部服务。每个工具都可开箱即用
• Claude Code 插件——从市场一步安装，提供 20 个斜杠命令
• 指挥模式——通过一条指令编排完整乐队，并自动检测模板（爵士小乐队、摇滚乐队、电子乐、氛围音乐等）
• 原生面向 Agent——3 个 MCP 资源可教会任何已连接的 Agent Strudel 语言，使其能够创作原创音乐，而不只是从预设中挑选

演奏方式

模式	命令	描述
Claude Code 插件	/plugin install dj-claude	斜杠命令 + MCP 服务，一步安装
Web 应用	claude.dj	单 Agent 浏览器体验，无需 API 密钥
终端 TUI	npx dj-claude	交互式终端 DJ
TUI + Web 音频	npx dj-claude --browser	使用浏览器音频引擎的 TUI，音质更佳
无头模式	npx dj-claude --headless "lofi"	便于脚本和自动化，播放后退出（使用 --duration N 设置秒数，默认 10）
MCP 服务	npx dj-claude-mcp	用于 AI Agent 集成（Cursor、Windsurf、Zed 等）
MCP HTTP 服务	npx dj-claude-mcp-http	通过 HTTP 进行多 Agent 即兴合奏

**终端音频与浏览器音频：**默认情况下，CLI 和 MCP 服务通过 node-web-audio-api 渲染音频——这是 Web Audio API 的 Node.js 重实现。它无需配置即可在任何环境中运行，但采样播放和效果可能不如真实浏览器引擎自然。添加 --browser（CLI）或设置 DJ_CLAUDE_BROWSER=1（MCP），即可将音频路由到系统浏览器的原生 Web Audio。此方式会打开一个后台标签页，带来明显更高的音质——尤其适用于铺底音色、混响和分层模式。

快速开始

前置条件

• Node.js >= 18
• Anthropic API 密钥——可选。用于通过文本提示词生成 AI 音乐。没有密钥时，仍可通过预设、直接编写 Strudel 代码，或使用 code/layers 参数调用所有工具

安装并运行

# Set your API key (or add to a .env file)
export ANTHROPIC_API_KEY=sk-ant-...

# Launch the terminal DJ
npx dj-claude

或者全局安装：

npm i -g dj-claude
dj-claude

或者使用无头模式运行脚本：

npx dj-claude --headless "jazzy lo-fi beats" --duration 30

Claude Code 插件

这是在 Claude Code 中使用 DJ Claude 最简单的方式。它会安装 MCP 服务并提供斜杠命令。

安装

/plugin marketplace add p-poss/dj-claude
/plugin install dj-claude@dj-claude-marketplace

斜杠命令

命令	描述
/dj-claude:play [prompt]	根据描述播放音乐
/dj-claude:play-preset [name]	从 22 种精选模式中选择播放
/dj-claude:vibe [mood]	设置氛围 — chill、dark、hype、focus、funky、dreamy、weird、epic
/dj-claude:live-mix [prompt]	自主 DJ 演出 — 在一轮对话中呈现 5-6 个不断演变的阶段
/dj-claude:jam [role] [prompt]	为即兴演奏会话添加一个声部（鼓、贝斯、旋律等）
/dj-claude:jam-clear [role]	移除一个或所有声部
/dj-claude:jam-status	显示所有启用的即兴演奏声部
/dj-claude:hush	停止所有音乐
/dj-claude:now-playing	查看当前正在播放的内容
/dj-claude:strudel [code]	直接运行原始 Strudel 代码
/dj-claude:browser	在会话中切换 Node 和浏览器音频后端
/dj-claude:context [activity]	设置编码情境，让音乐适应你的工作
/dj-claude:preview [role] [prompt]	预览一个即兴演奏声部，但不将其添加到演奏中
/dj-claude:analyze	分析混音的频率平衡并提供建议
/dj-claude:conduct [directive]	根据单条指令编排完整乐队
/dj-claude:save [name]	将当前混音保存为命名快照
/dj-claude:load [name]	恢复已保存的混音快照
/dj-claude:list-saves	列出所有已保存的快照
/dj-claude:export	导出带有头部注释的当前 Strudel 代码
/dj-claude:connect [port]	启动 HTTP 服务并配置项目，以支持多 Agent 即兴演奏会话

也可以直接用自然语言提出请求 — Claude 会调用合适的工具：

> play some chill lo-fi while I work on this PR
> set the vibe to hype
> hush

自动允许权限

默认情况下，Claude Code 每次调用 MCP 工具时都会请求权限。若要让 DJ Claude 不间断地播放音乐，请将以下内容添加到 .claude/settings.json：

{
  "permissions": {
    "allow": [
      "mcp__dj-claude__play_music",
      "mcp__dj-claude__play_strudel",
      "mcp__dj-claude__set_vibe",
      "mcp__dj-claude__live_mix",
      "mcp__dj-claude__hush",
      "mcp__dj-claude__now_playing",
      "mcp__dj-claude__jam",
      "mcp__dj-claude__jam_clear",
      "mcp__dj-claude__jam_status",
      "mcp__dj-claude__set_context",
      "mcp__dj-claude__jam_preview",
      "mcp__dj-claude__mix_analysis",
      "mcp__dj-claude__conduct",
      "mcp__dj-claude__conduct_evolve",
      "mcp__dj-claude__snapshot_save",
      "mcp__dj-claude__snapshot_load",
      "mcp__dj-claude__snapshot_list",
      "mcp__dj-claude__export_code",
      "mcp__dj-claude__play_preset",
      "mcp__dj-claude__switch_audio"
    ]
  }
}

MCP 服务（手动设置）

如需完整的 MCP 工具参考、无密钥操作指南和多 Agent 详情，请参阅 docs/MCP.md。

如果你更喜欢手动配置，或想在其他 MCP 客户端（Cursor、Windsurf、Zed 等）中使用 DJ Claude，请将以下内容添加到 .mcp.json：

{
  "mcpServers": {
    "dj-claude": {
      "command": "npx",
      "args": ["-y", "dj-claude-mcp"]
    }
  }
}

如需通过浏览器的 Web Audio 引擎获得更高音质：

{
  "mcpServers": {
    "dj-claude": {
      "command": "npx",
      "args": ["-y", "dj-claude-mcp"],
      "env": {
        "DJ_CLAUDE_BROWSER": "1"
      }
    }
  }
}

MCP 工具

每个工具都无需 API 密钥即可使用——通过 code/layers 参数直接传入 Strudel，或使用 play_preset/set_vibe 轻松播放音乐。添加 ANTHROPIC_API_KEY 即可解锁根据文本提示词进行 AI 生成。

工具	描述	无需密钥？
play_preset	从精选预设库播放（涵盖情绪、流派和活动的 22 种模式）	是
play_music	播放音乐——通过 prompt（AI）或 code（直接使用 Strudel）	是，通过 code
play_strudel	直接运行原始 Strudel/Tidal 代码	是
set_vibe	设置氛围——chill、dark、hype、focus、funky、dreamy、weird、epic	是
live_mix	自主 DJ 演出——通过 prompt（AI）或 stages_code（Strudel 数组）	是，通过 stages_code
jam	添加/更新音轨——通过 prompt（AI）或 code（直接使用 Strudel）	是，通过 code
jam_clear	从即兴演奏会话中移除一个或所有音轨	是
jam_status	显示所有活动音轨及其角色名称和代码	是
jam_preview	预览即兴演奏音轨，但不添加它——通过 prompt 或 code	是，通过 code
conduct	编排完整乐队——通过 directive（AI）或 layers 映射	是，通过 layers
conduct_evolve	演变音轨——通过 directive（AI）或 layers 映射	是，通过 layers
mix_analysis	分析混音的频率平衡、增益和建议	是
hush	停止所有音乐播放	是
now_playing	查看当前正在播放的内容	是
switch_audio	在运行时切换 Node 和浏览器音频后端	是
set_context	设置编码上下文，让音乐适应你的活动	是
snapshot_save	将当前混音保存为命名快照	是
snapshot_load	恢复之前保存的快照	是
snapshot_list	列出所有已保存的快照	是
export_code	导出带有头部注释的当前 Strudel 代码	是

MCP 资源

此服务将 Strudel 知识作为 MCP 资源公开，以便 Agent 学习语法并编写自己的代码：

资源	描述
strudel://reference	完整的 Strudel 语法参考——核心函数、迷你记谱法、效果和调制
strudel://roles	构建即兴演奏音轨的音乐角色指南（鼓、贝斯、旋律、和弦等）
strudel://examples	预设库中的可运行 Strudel 模式，按情绪、流派和活动分类

Agent 可以读取这些资源、学习语法，然后调用 play_music(code: ...)、jam(code: ...) 或 conduct(layers: ...)——无需 API 密钥。

无需密钥即可使用

每个工具都无需 ANTHROPIC_API_KEY 即可使用。无需密钥的用法分为三个层级：

1. 零操作——预设和氛围

play_preset(name: "jazz")          # 22 curated patterns
set_vibe(mood: "chill")            # 8 mood presets

2. 直接编写代码——Agent 编写 Strudel

play_music(code: 'stack(s("bd*4").gain(0.75), note("c2").s("sawtooth").lpf(300))')
jam(role: "drums", code: 's("bd*4").gain(0.75)')
conduct(layers: { drums: 's("bd*4")', bass: 'note("c1").s("sine")' })

3. 全功能——Agent 从资源中学习 Strudel

Agent 可以读取 strudel://reference 学习完整语法，读取 strudel://roles 获取构建音轨的指南，并读取 strudel://examples 查看可运行的模式——然后编写自己的原创 Strudel 代码。

这意味着任何通过 MCP 连接的 AI Agent 都可以创作音乐，无论是否设置了 ANTHROPIC_API_KEY。发起调用的 Agent 本身就是大模型。

多 Agent 即兴演奏会话

多个 Agent 可以使用 HTTP 传输和即兴演奏工具实时协作创作音乐。每个连接的客户端都有自己的 MCP 会话，但它们共享同一个音频引擎和音轨状态——一个 Agent 添加鼓点，另一个添加贝斯，然后通过 stack() 自动叠加音轨。

Claude Code

运行 /dj-claude:connect，即可自动启动 HTTP 服务并一步完成项目配置：

/dj-claude:connect
/dj-claude:connect 8080   # custom port

这会启动 HTTP MCP 服务、写入 .mcp.json，并使同一项目中的所有其他 Claude Code 会话自动连接。

其他 Agent（Cursor、Windsurf、OpenClaw 等）

手动启动 HTTP 服务：

# Default port 4321
npx dj-claude-mcp-http

# Or with a custom port
DJ_CLAUDE_PORT=8080 npx dj-claude-mcp-http

然后将 MCP 客户端指向此端点：

{
  "mcpServers": {
    "dj-claude-http": {
      "type": "http",
      "url": "http://127.0.0.1:4321/mcp"
    }
  }
}

Jam 工具工作流

使用 AI 生成（需要 API 密钥）：

Agent 1: jam(role: "drums", prompt: "four-on-the-floor house kick")
Agent 2: jam(role: "bass", prompt: "deep sub bass in C minor")

使用直接代码（无需 API 密钥）：

Agent 1: jam(role: "drums", code: 's("bd*4").gain(0.75)')
Agent 2: jam(role: "bass", code: 'note("c1 ~ c1 ~").s("sawtooth").lpf(300).gain(0.5)')
Agent 1: jam_status               # see all active layers
Agent 2: jam_clear(role: "bass")  # remove just the bass layer

指挥模式

通过单条指令编排完整乐队 — conduct 会一次生成多个声部。

使用 AI 生成（需要 API 密钥）：

conduct(directive: "jazz combo in C minor, late night mood")
# → creates drums, bass, chords, melody layers automatically

使用直接代码（无需 API 密钥）：

conduct(layers: {
  drums: 's("bd*4").gain(0.75)',
  bass: 'note("c1 ~ c1 ~").s("sawtooth").lpf(300).gain(0.5)',
  chords: 'note("<[c3,eb3,g3] [ab2,c3,eb3]>/2").s("triangle").gain(0.3)'
})

系统会根据指令自动检测乐队模板：

• 爵士乐队 — 鼓、贝斯、和弦、旋律
• 摇滚乐队 — 鼓、贝斯、和弦、主奏
• 电子乐 — 鼓、贝斯、铺底音、主奏、音效
• 氛围音乐 — 铺底音、氛围、音效、旋律
• 完整乐队 — 鼓、贝斯、和弦、旋律、铺底音、音效
• 极简 — 鼓、贝斯、旋律
• 管弦乐 — 贝斯、和弦、铺底音、旋律、音效、氛围

使用 conduct_evolve 让所有声部逐阶段演化：

conduct_evolve(directive: "shift darker", stages: 3)
# → evolves each layer 3 times with 15s pauses

# Or provide evolved code directly (no API key):
conduct_evolve(layers: { drums: 's("bd ~ sd ~").gain(0.7)' })

混音快照

保存和恢复混音：

snapshot_save(name: "verse1")    # save the current mix
snapshot_save(name: "drop")      # save another version
snapshot_list                    # see all saved snapshots
snapshot_load(name: "verse1")    # restore and resume playback
export_code                      # get raw Strudel code with headers

终端 TUI 功能

• 实时模式可视化 — 播放音乐时，DancingClaude 和代码显示之间会出现实时 ASCII 钢琴卷帘和鼓点网格，展示与音频同步的音符位置和节奏模式
• DancingClaude — 随节拍起舞的动画像素艺术
• 实时代码显示 — 随音乐流播放，显示当前 Strudel 模式

键盘快捷键（TUI）

按键	操作
Enter	提交提示词
q	退出
Esc	暂停 / 恢复音乐
r	恢复到上一个模式

Web 应用

访问 claude.dj，体验单 Agent 浏览器版 — 无需 API 密钥或安装。

功能：

• 5 种俱乐部主题 — Anthropic、Gemini、Codex、Fairlight、OpenClaw
• NIGHT 模式（颜色反转）、DISCO 模式（彩虹色相循环）、RAVE 模式（辉光 + CRT 扫描线）
• LIVE MIX 模式 — 自动驾驶 DJ，无需用户输入，每约 60 秒自动演化音乐
• 语音 DJ 评论，包含空闲时的炒热气氛短句（通过 ElevenLabs TTS）
• 跟随光标移动的 Dancing Claude
• 实时 Strudel 代码显示，可导出到剪贴板
• 按空格键切换播放 / 暂停

环境变量

变量	必需	描述
ANTHROPIC_API_KEY	否	启用根据文本提示词进行 AI 生成。没有此变量时，所有工具仍可使用 — 可使用 play_preset、set_vibe、play_strudel，或通过 code/layers/stages_code 参数传入 Strudel 代码
ELEVENLABS_API_KEY	否（仅限 Web）	启用语音 DJ 评论
DJ_CLAUDE_BROWSER	否	在 MCP 模式下设为 1，以启用浏览器音频后端
DJ_CLAUDE_PORT	否	多 Agent 模式的 HTTP 服务端口（默认：4321）
DJ_CLAUDE_MODEL	否	CLI/MCP 使用的 Claude 模型（默认：claude-sonnet-4-6）
DJ_CLAUDE_MAX_TOKENS	否	CLI/MCP 的最大响应词元数（默认：16384）

CLI 还会自动从你的项目目录加载 .env 和 .env.local 文件。

架构

DJ Claude 是一个 Next.js 应用，附带一个 CLI 包：

• /app — Next.js Web 前端（claude.dj）
• /cli — 终端 TUI（Ink/React）和 MCP 服务
• /cli/src/mcp — MCP 工具定义和 JSON-RPC 服务
• /cli/src/audio — Strudel 音频引擎（Node 和浏览器后端）
• /cli/src/lib — 共享实用工具、Claude API 客户端、提示词生成
• /plugin — Claude Code 插件（技能、MCP 配置、市场）

音乐由 Claude 编写的 Strudel 实时编程模式生成，然后通过 Node node-web-audio-api 后端或浏览器原生 Web Audio API 实时执行。

平台支持

支持 macOS、Windows 和 Linux。在 Linux 上，Node 音频后端（node-web-audio-api）需要 JACK 或 PipeWire-JACK — 仅使用原版 ALSA/PulseAudio 无法运行预编译二进制文件。使用 --browser 模式即可绕过此限制，改为通过浏览器传输音频。

创作者

由 Patrick Poss 构建 — [email protected]

许可证

GNU AGPL-3.0-or-later

DJ Claude 使用 Strudel 生成并播放音乐。Strudel 是 TidalCycles 的移植版本，由 Alex McLean 及贡献者开发，并采用 AGPL-3.0 许可证。由于 DJ Claude 捆绑并提供 Strudel 服务，包括通过网络在 claude.dj 上提供，因此组合后的作品采用相同的 AGPL-3.0 许可证分发。完整的对应源代码可在此代码仓库中获取。