clify Monorepo

The clify monorepo unites two complementary terminal music products:

1. cliamp-clify — A feature-rich fork of cliamp (retro Winamp-inspired terminal music player in Go) with native Spotify superpowers: Made For You mix resolution, Spotify-derived Recently Played albums & playlists, Top Artists with correct album counts, Followed playlists viewport/filter fixes, headless spotify login, default Spotify launch, and Omarchy live theme sync for visualizers.
2. clify CLI & ADD Framework — A complementary Python CLI tool and reference implementation of the Metric-Driven Agent-Driven Development (AGENTS.md) specification, extending cliamp-clify with cross-provider library unification, natural-language playback agents, PKCE OAuth, and deterministic SLA guardrails.

DJ mode foundation is now shared across both products: Go dual-deck/fader/BPM primitives live in cliamp-clify/player, while the Python DjAgent provides scope-gated DJ command routing. See docs/dj.md for the current implementation boundary.

---

System Architecture

graph TD
    subgraph Monorepo ["Turborepo Root (turbo.json)"]
        direction TB

        subgraph Product1 ["cliamp-clify (Go / TUI Player & Daemon)"]
            TUI["Winamp-Style Terminal UI<br/>(Bubbletea & Lip Gloss)"]
            Engine["Audio Engine & Providers<br/>(Beep & go-librespot)"]
            ForkMods["Spotify Superpowers:<br/>• Made For You Mix Resolution<br/>• Spotify-derived Recently Played<br/>• Followed Playlists Viewport Fix<br/>• Headless 'spotify login'"]
            IPC["IPC Socket Server<br/>(cliamp.history.unified/1)"]
            TUI --- Engine
            Engine --- ForkMods
            Engine --- IPC
        end

        subgraph Product2 ["clify (Python / CLI & Agents)"]
            CLI["clify CLI<br/>(library, recent, play, status, spotify login)"]
            Agents["ADD Agents & Orchestrator<br/>(CliampPlaybackAgent, LibrarySyncAgent)"]
            SpotClient["Spotify Web API Client<br/>(PKCE OAuth, Rate Limiting, Cache)"]
            UnifyLib["Unified Library Layer<br/>(Cross-Provider Merging & Dedup)"]
            CLI --- Agents
            CLI --- UnifyLib
            UnifyLib --- SpotClient
        end

        IPC <== "Unix Socket / Subprocess CLI" ==> UnifyLib
        IPC <== "Playback Control Verbs" ==> Agents
    end

Loading

---

Products & Features

1. cliamp-clify (Retro Terminal Music Player Fork)

• Made For You Mixes: Resolves Spotify-generated algorithmic playlists (Daily Mixes, Discover Weekly, Release Radar, Daylist, On Repeat, Repeat Rewind) via go-librespot context-resolution (/context-resolve/v1/{uri}), overcoming Spotify's November 2024 Web API restrictions.
• Spotify-derived Recently Played: Dynamic album and playlist rows derived from recent listening context, deduplicated by canonical URI with session caching.
• Default Spotify Provider: Opens straight to the Spotify browser on launch with clean queue state.
• Followed Playlists Viewport Fixes: Header-aware scroll calculation keeps bottom rows visible; / filter mode preserves section headers and result count.
• Headless spotify login: Built-in PKCE login command authorizing the player without starting audio playback.
• Omarchy theme sync: When no theme is configured, UI and spectrum visualizer colors follow ~/.local/state/omarchy/current/theme/colors.toml and hot-reload on desktop theme changes.
• Spotify Top Artists: Artist browse rows show real album counts (enriched from Spotify's albums API).
• Versioned IPC Contract: Exposes cliamp.history.unified/1 over Unix socket for companion tools.
• DJ mode: Press D for the dual-deck control screen. It exposes deck focus, crossfader, pitch nudge, and confidence-gated sync. Live speaker-graph mixing and public DJ CLI commands are still in development.

2. clify (Extended Spotify CLI & ADD Framework)

• Unified Library Querying (clify library): Merges local cliamp listening history and Spotify Web API library into a structured, sorted view (Recently Played → Library → Your Playlists → Made For You).
• Cross-Provider History (clify recent): Timestamped, deduplicated song history across all active providers with graceful provider outage isolation (partial: true).
• Natural Language Playback Control (clify play): Agent-orchestrated command routing with strict scope guardrails (§2.2) and post-action verification.
• Headless PKCE OAuth (clify spotify login): Mode-0600 token storage (~/.config/clify/spotify.json) with automated token refresh and credential redaction.
• Metric-Driven ADD Guardrails: Deterministic SLAs on every execution (latency ≤ 2.5s, cost ≤ $0.02, confidence ≥ 0.90), safe failure modes, and runtime time-series monitoring.
• DJ agent: DjAgent routes requests such as “blend into the next song” and “sync deck B” under dj.read/dj.control scopes.

---

Monorepo Quickstart (Turborepo)

Prerequisites: Node.js ≥ 18, pnpm ≥ 9, Go ≥ 1.26, Python ≥ 3.10.

# Clone the monorepo
git clone https://github.com/harlanljones/clify.git

cd clify

# Install monorepo dependencies (Turborepo)
pnpm install

# Build all targets (cliamp-clify Go binary + clify Python package)
pnpm build

# Run all test suites in parallel with caching (Go tests + Pytest suite)
pnpm test

# Run code quality and verification checks across all packages
pnpm check

---

Product Quickstarts

Using cliamp-clify (Terminal Music Player)

1. Build and install the player binary:

   cd cliamp-clify
   make build
   make install   # installs to ~/.local/bin/cliamp

2. Headless Spotify sign-in (PKCE OAuth):

   cliamp spotify login --client-id <YOUR_SPOTIFY_CLIENT_ID>

3. Launch the player:

   cliamp         # opens Winamp-style TUI with Spotify provider focused

4. Run headless background daemon:

   cliamp --daemon &

Using clify CLI & Agent Framework

1. Install the Python package:

   pip install -e packages/clify

2. Authenticate with Spotify Web API:

   clify spotify login --client-id <YOUR_SPOTIFY_CLIENT_ID>

3. Query library and control playback:

   # Unified library overview
   clify library
   
   # Machine-readable JSON output
   clify library --json
   
   # Merged listening history
   clify recent --limit 20
   
   # Inspect current player status
   clify status
   
   # Natural-language playback instruction via ADD agent orchestrator
   clify play "toggle playback"

4. Programmatic Python API:

   from cliamp_agents import CliampQueryAgent
   from cliamp_playback import CliampPlaybackAgent
   from orchestrator import Orchestrator
   from monitoring import TelemetryRegistry
   
   query = CliampQueryAgent()        # read-only: playlists, history, status
   playback = CliampPlaybackAgent()  # playback.control agent
   orchestrator = Orchestrator([playback, query])
   registry = TelemetryRegistry()
   
   telemetry = orchestrator.run("what's currently playing?")
   registry.record(telemetry)
   print(telemetry["response"])                  # {'status': 'SUCCESS', 'data': [...]}
   print(telemetry["metrics"]["sla_compliant"])  # True

---

Repository Layout

.
├── cliamp-clify/               # Product 1: Go TUI music player fork
│   ├── cmd/                    # CLI commands (spotify login, history, etc.)
│   ├── external/spotify/       # Spotify provider, recent history, Made For You resolution
│   ├── ipc/                    # Versioned Unix socket IPC server
│   ├── ui/                     # Bubbletea & Lip Gloss Winamp-style interface
│   ├── Makefile                # Go build, test, and vet targets
│   └── package.json            # Turborepo workspace bridge
│
├── packages/clify/             # Product 2: Python CLI & ADD framework
│   ├── clify_cli.py            # CLI entrypoint (library, recent, play, status)
│   ├── spotify_client.py       # Spotify Web API client (PKCE, rate limits, caching)
│   ├── spotify_auth.py         # PKCE OAuth login server & token storage
│   ├── unified_library.py      # Cross-provider aggregator & deduplicator
│   ├── cliamp_client.py        # Subprocess wrapper for cliamp JSON commands
│   ├── cliamp_playback.py      # Scoped playback control agent
│   ├── core_agents.py          # ScopeGuard, BaseAgent, LibrarySyncAgent
│   ├── orchestrator.py         # ADD orchestrator with token budgeting
│   ├── monitoring.py           # TelemetryRegistry time-series monitoring
│   ├── tests/                  # 200+ unit, contract, and lifecycle tests
│   ├── pyproject.toml          # Python package configuration
│   └── package.json            # Turborepo workspace bridge
│
├── docs/                       # Specifications, schemas, and fork plans
│   ├── cliamp_schemas.md       # Pinned cliamp JSON schemas & failure contract
│   ├── spotify_schemas.md      # Pinned Spotify Web API contracts
│   ├── cliamp_clify_fork_plan.md # Initial fork specification
│   └── cliamp_clify_v2_plan.md # v2 Made For You & Recently Played plan
│
├── .github/workflows/          # CI/CD pipelines
│   └── test.yml                # Turborepo multi-suite CI matrix
├── pnpm-workspace.yaml         # Turborepo workspace definition
├── turbo.json                  # Turborepo pipeline configuration
├── AGENTS.md                   # Metric-Driven ADD Technical Specification
├── ROADMAP.md                  # Unified development roadmap
├── CHANGELOG.md                # Project changelog
└── package.json                # Root Turborepo manifest

---

Guardrails & Metric-Driven ADD Compliance

Every agent operation in clify satisfies the strict boundaries of AGENTS.md:

• Scope boundary enforcement (§2.2): Prohibited operations (e.g. playback.control, user.billing) are rejected deterministically before any tool execution.
• SLA Telemetry (§3): Every execution tracks latency ($L \le 2.5s$), cost ($C_x \le $0.02$), token efficiency, and semantic accuracy ($A_s \ge 0.90$).
• Safe Failure Modes (§4.2): Tool errors return {"status": "TOOL_ERROR", "retry_allowed": true}; self-correction loops are capped at 3 iterations.
• Runtime Monitoring (§5): Sliding-window latency, cost accumulators, and validation failure tracking with automated mitigation alerts.
• Three-Stage TDD Lifecycle (§4): All agents pass Red $\rightarrow$ Green $\rightarrow$ Refactor pipeline verification before release.

---

Running Test Suites

Run all tests across both Go and Python workspaces with Turborepo caching:

pnpm test

Or run package-specific test suites directly:

# Go test suite (cliamp-clify)
cd cliamp-clify && go test ./...

# Python test suite (clify)
cd packages/clify && pytest

---

License

MIT © 2026 harlan