github.com/LargeModGames/spotatui (link)

# AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

This file is maintained as three near-identical copies: `CLAUDE.md`, `AGENTS.md`, and
`.github/copilot-instructions.md` (only the opening lines differ). Edit all three together.

## Build & Run

```bash
# Full build (native streaming + audio viz + Lua scripting + OS integrations)
cargo run

# Slim build - no librespot/audio/scripting; fastest iteration, one of CI's seven legs
cargo run --no-default-

### The DJ: lanes, guards, and the avoid-library filter

The tool surface is defined once - `src/infra/dj/tools.rs::TOOLS` (8 tools). MCP
publishes it verbatim; the in-TUI brain renders the same table into its prompt.

- **Lanes**: `AskDj` / `DjTopUp` run on the service lane (a brain call can take
  minutes; they touch only `App` and use `dispatch_without_spinner` - plain
  `dispatch` would pin the global spinner for the whole call). `DjToolCall` /
  `DjIndexLibrary` run on the serial lane because they need

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

This file is maintained as three near-identical copies: `CLAUDE.md`, `AGENTS.md`, and
`.github/copilot-instructions.md` (only the opening lines differ). Edit all three together.

## Build & Run

```bash
# Full build (native streaming + audio viz + Lua scripting + OS integrations)
cargo run

# Slim build - no librespot/audio/scripting; fastest iteration, one of CI's seven legs
cargo run --no-d

### CLI subcommands

Subcommands are assembled in `src/runtime/cli.rs::build_clap_app` and
dispatched in `src/runtime/mod.rs::run_cli`, where **dispatch order encodes
auth requirements**: `history`, `mcp`, and `plugin` return before config/auth
load; playback commands require a Spotify session.
Place new subcommands deliberately. stdout is protocol/output-only (`mcp` writes
JSON-RPC, `history recap` writes HTML) - diagnostics go to stderr; never add a
`println!` on a path a subcommand can reach. Self-update

### Lua plugins (feature `scripting`)

Plugins never see `&mut App` or rspotify types: reads are cached serde snapshots
from `src/core/plugin_api.rs`; writes are shared-vocabulary `Action`s
(`src/core/action/`) the engine drains through `App::apply` while holding
`&mut App`, each routed through the same `App` method the equivalent keybinding
uses, where the terminal has one (`default_binding` in `src/tui/keymap.rs`
records which variants have none). Snapshot changes must be additive
(`#[serde(default)]`, ne

### MCP server (feature `mcp-server`)

`spotatui mcp` is a stdio relay to the running TUI over loopback TCP: the TUI
listens on 127.0.0.1 with a token published in a 0600
`~/.config/spotatui/mcp.json`, gated on `behavior.mcp_enabled`. The relay
reconnects per line because the two processes have independent lifetimes.
`spotatui mcp` blocks - use `spotatui mcp status` to test. The protocol
(`src/infra/mcp/protocol.rs`) is hand-rolled: keep MCP *protocol* errors (unknown
tool, bad args) distinct from tool *exe

# Copilot Instructions for spotatui

This file is maintained as three near-identical copies: `CLAUDE.md`, `AGENTS.md`, and
`.github/copilot-instructions.md` (only the opening lines differ). Edit all three together.

## Build & Run

```bash
# Full build (native streaming + audio viz + Lua scripting + OS integrations)
cargo run

# Slim build - no librespot/audio/scripting; fastest iteration, one of CI's seven legs
cargo run --no-default-features --features telemetry,tui

# With the alternative sources (Local/

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "spotatui": {
      "type": "stdio",
      "command": "spotatui",
      "args": [
        "mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "spotatui": {
      "type": "stdio",
      "command": "spotatui",
      "args": [
        "mcp"
      ]
    }
  }
}

---
name: spotatui-dj
description: Be the DJ for spotatui, the terminal music player, by driving its MCP server. Use whenever the user asks for music, asks you to DJ, wants tracks queued, played, skipped, or searched, asks what they have been listening to, or mentions spotatui.
---

# DJ for spotatui

You control a music player the user is watching. Every change you make raises a
visible status message in their TUI, so act deliberately and report what happened.

## Before anything else

The eight spotatui t

# yaml-language-server: $schema=https://storage.googleapis.com/coderabbit_public_assets/schema.v2.json
language: en-US
tone_instructions: >-
  Write plainly and directly. Do not use em-dashes; use commas, colons, or
  separate sentences instead. Prefer concrete detail over praise.

reviews:
  profile: chill
  # Approve only once review comments are resolved and checks pass.
  request_changes_workflow: true
  poem: false

  path_filters:
    - "!Cargo.lock"
    - "!flake.lock"
    - "!spotatui.wiki/**"
    -