DJ Agent
A terminal-based Spotify DJ that understands natural language, controlling the macOS Spotify desktop app via AppleScript, searching and queueing through the Spotify Web API, and parsing intent with an LLM.
DJ Agent is a small macOS side project that lets a user type either structured commands or plain English into a terminal and have music respond. Input like "put on some OneRepublic" or "turn it up" is normalized by an LLM into one of roughly 20 canonical commands, which the agent then executes. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
What it does
The command surface covers playback (play, pause, resume, next, prev), discovery (search with an optional result count), queue management (queue by name, by index from the last search, or all results; remove; show; clear), and player control (volume, shuffle, repeat, devices, now playing). Natural-language phrasing maps onto these same commands when an LLM key is configured. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
Stack and dependencies
It requires macOS (AppleScript drives the desktop app), Python 3.11 or newer, a Spotify
Premium account, the Spotify desktop app, and a Spotify Developer app for API credentials.
Natural language is optional and gated behind a DEDALUS_API_KEY, with the model selectable
via a MODEL variable that defaults to an Anthropic Claude Sonnet model. Search uses Spotify
client credentials, queueing uses a one-time user OAuth flow with a cached token, and playback
uses AppleScript. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31
Notes
The optional language layer routes through a Dedalus API key, making the project a small consumer-facing demonstration of the same agent loop Kevin works on professionally. The three-layer control flow (LLM normalizer, command executor, AppleScript plus Web API backends) is documented in DJ Agent Control Flow.
Current Evidence (2026-07-01)
This page was refreshed against Kevin's live GitHub inventory, pinned repositories, PortfolioMon cards, README scrape, and downloaded portfolio screenshots. Treat this section as the current evidence anchor; deeper interpretation stays in the surrounding compiled truth.
| GitHub repo | Visibility | Language | Stars | Last push | Homepage |
|---|---|---|---|---|---|
| Kevin-Liu-01/dj-agent | private | Python | 1 | 2026-03-26 | n/a |
Timeline
-
2026-07-01 | Project graph refresh checked this page against Kevin's live GitHub inventory, pinned repos, scraped PortfolioMon cards, READMEs, and portfolio screenshots; current evidence was added above. Source: raw/github/kevin-repos-2026-07-01.json; raw/github/kevin-pinned-repos-2026-07-01.json; raw/sites/kevinliu-biz-2026-07-01/portfolio-projects.json
-
2026-05-31 | Project page created from the DJ Agent repository README. Captured the natural-language-to-command DJ loop, the ~20 command surface, and the macOS plus Spotify plus optional Dedalus stack. Source: ~/Documents/GitHub/dj-agent/README.md, 2026-05-31