Spotify Portal AI Plugins: Bring Portal CLI to Three Coding Agents
A plugin that connects Claude Code, Codex, and Cursor to Spotify Portal for catalog search, service briefings, and safe action invocation.
GitHub spotify/portal-ai-plugins Updated 2026-10-08 Branch main Stars 2.4K Forks 198
TypeScript Shell Portal CLI Claude Code / Codex / Cursor

🧭 Decision Guide

Try it if you

  • You need access to the Spotify Portal software catalog from Claude Code, Codex, or Cursor
    The README opening says “Bring Spotify Portal into Claude Code, Codex, and Cursor,” and Highlights includes software catalog search
  • You need natural-language Portal documentation search and service briefings
    The README's Highlights and Workflows sections list search and service
  • You want Portal actions with help, dry-run, and confirmation safeguards
    The README Highlights says actions includes “help, dry-run, and confirmation safeguards”
  • You use Claude Code and want to delegate I/O-heavy work to AiKA worker models
    The README Highlights says shunt currently supports only Claude Code and uses the Portal CLI actions registry to run AiKA modes

Skip it if you

  • Your team must depend on formal releases rather than the current No releases state
    Project metadata shows 0 releases and the latest version is “No releases”
  • You use Codex or Cursor but require shunt's AiKA delegation capability
    The README explicitly says “shunt (Claude Code only for now)”
  • Your environment cannot use the Portal CLI commands auth, actions, owner, search, and service
    The README Portal CLI section says setup verifies these five commands

Requirements

  • You need one of Claude Code, Codex, or Cursor; the README Installation section gives separate paths for all three.
  • You need a usable Portal CLI; the README says workflows invoke the upstream CLI through “npx @spotify/portal-cli <command>”.
  • You need Portal CLI authentication configured; the README defines setup as “Configure Portal CLI authentication”.
  • For Cursor, register spotify/portal-ai-plugins in the Cursor team marketplace, then install it from Cursor Settings → Plugins.

First step (verbatim from README)

claude plugin marketplace add spotify/portal-ai-plugins

Watch out

  • Installing shunt in Claude Code is optional; the command includes an “optional” comment
    The README Claude Code installation block contains “claude plugin install shunt@portal # optional: token-saving AiKA delegation”
  • Codex cannot copy the Claude Code /portal:setup flow
    The README Codex section requires opening /plugins, installing Spotify Portal, and asking “Set up Spotify Portal for me.”
  • setup does more than configure authentication: it verifies auth, actions, owner, search, and service
    The README Portal CLI section explicitly lists the five commands verified by setup

Not stated in the README

  • The README does not specify minimum versions for Portal CLI, Node.js, or any coding agent.
  • The README does not explain the credentials, login flow, or permission scope required for Spotify Portal authentication.
  • The README does not provide input parameters, output formats, or error-handling details for search, service, or actions.
  • The README does not list the specific Portal actions or identify which actions support dry-run.
  • The README does not explain what changed in the 6 recent commits, and there are no releases to assess version compatibility.

💡 Deep Analysis

6
Yes I primarily use Codex rather than Claude Code. I need to install the Spotify Portal plugin, complete Portal CLI authentication, and then search the software catalog and technical documentation. Is this project usable in Codex?
For: A Spotify internal developer using Spotify Portal in Codex who must complete CLI authentication and command-readiness checks first

Yes. The README explicitly provides a Codex installation path and a natural-language setup entry point, but you must install Spotify Portal from /plugins before starting a new task.

  • Codex installation begins by adding the spotify/portal-ai-plugins marketplace and running codex.
  • The README instructs users to install Spotify Portal in /plugins and ask it to set up Spotify Portal in a new task.
  • setup configures Portal CLI authentication, while the workflows invoke @spotify/portal-cli through npx.
  • shunt currently supports Claude Code only, so Codex users should not assume AiKA-based low-cost worker routing is available. The README does not state whether Codex exposes exactly the same interaction details as Claude Code.
  • Installation / Codex: `codex plugin marketplace add spotify/portal-ai-plugins`
  • Installation / Codex: Open `/plugins`, install Spotify Portal, start a new task, and ask: `Set up Spotify Portal for me.`
  • Highlights: The marketplace also ships shunt (Claude Code only for now)
codex plugin marketplace add spotify/portal-ai-plugins
Not stated in the README:The README does not specify Codex version compatibility or how available commands are surfaced.;The README does not say whether action confirmation behaves the same way in Codex and Claude Code.
It depends I use Claude Code and frequently handle bulk file reads and boilerplate generation. I want to route I/O-heavy work to cheaper worker models through the Portal CLI actions registry and AiKA. Does shunt fit this constraint?
For: A Spotify internal developer using Claude Code who wants to delegate bulk file reads and boilerplate generation to cheaper worker models

It depends. shunt closely matches bulk file reading and boilerplate generation, but it is limited to Claude Code and depends on AiKA modes and the Portal CLI actions registry.

  • The README describes shunt as routing I/O-heavy agent work and explicitly gives bulk file reads and boilerplate generation as examples.
  • It delegates through the Portal CLI actions registry to AiKA modes running cheaper worker models.
  • This is an optional plugin; it is not required for the search, service, or regular actions workflows.
  • The README does not identify the worker models or describe quality differences, data isolation, retry behavior, or cost accounting. The documentation therefore cannot establish the actual savings or trade-offs.
  • Highlights: The marketplace also ships **shunt** (Claude Code only for now)
  • Highlights: routes I/O-heavy agent work — bulk file reads and boilerplate generation — to AiKA modes running cheaper worker models
  • Highlights: via the Portal CLI actions registry
claude plugin install shunt@portal   # optional: token-saving AiKA delegation
Not stated in the README:The README does not identify the AiKA worker models, their context limits, or any code-quality guarantees.;The README does not say whether task data leaves the current execution environment or whether failures automatically fall back to the primary agent.
Yes I already work in Claude Code and need to search Spotify's software catalog and technical documentation, then quickly understand a service's owner, health, and incidents. Can this plugin reduce switching between Portal and my coding agent?
For: A Spotify internal developer using Claude Code who needs to search the Spotify software catalog and technical documentation

Yes. It is a good fit because it brings Portal search and service context into Claude Code workflows instead of requiring you to remember the full CLI command set.

  • search supports natural-language queries over the software catalog and technical documentation.
  • service summarizes available ownership, health, incident, and documentation details.
  • The plugin invokes Portal CLI through npx @spotify/portal-cli <command>, and setup verifies the auth, actions, owner, search, and service commands.
  • The README does not specify catalog freshness, search ranking behavior, or completeness guarantees for service briefings.
  • Highlights: Search the software catalog and technical documentation using natural language queries.
  • Highlights: Generate concise service briefings with available ownership, health, incident, and documentation details.
  • Portal CLI: Setup verifies the required `auth`, `actions`, `owner`, `search`, and `service` commands.
/portal:setup
Not stated in the README:The README does not say whether search supports filtering, sorting, or scoped data sources.;The README does not explain how service briefings behave when ownership, health, or incident data is missing.
Yes I maintain Portal CLI authentication and the runtime environment for a team, and need to distinguish plugin, CLI, authentication, and action-readiness problems. Can this project serve as a unified diagnostic entry point instead of requiring workflow-by-workflow troubleshooting?
For: A developer-tools maintainer responsible for Portal CLI authentication, the Node.js/npx runtime path, and read-only diagnostics in a Spotify internal environment

Yes. doctor is explicitly designed as a read-only readiness entry point and can separate plugin, CLI, authentication, and action-readiness checks. It is not, however, a full runtime monitor or permission-audit tool.

  • The README says doctor verifies the plugin, CLI, authentication, and action readiness.
  • setup configures authentication and verifies the auth, actions, owner, search, and service commands before proceeding.
  • Every workflow invokes the upstream CLI through npx @spotify/portal-cli <command>, so npx, network access, package resolution, and Portal CLI remain part of the dependency chain.
  • The README does not describe error codes, diagnostic output formats, CLI version constraints, offline behavior, or automatic repair. Complex failures may still require the CLI documentation or source code.
  • Highlights: Run read-only diagnostics to verify plugin, CLI, authentication, and action readiness.
  • Portal CLI: Setup verifies the required `auth`, `actions`, `owner`, `search`, and `service` commands before proceeding.
  • Portal CLI: The workflows invoke the upstream CLI through `npx @spotify/portal-cli <command>`
Not stated in the README:The README does not specify doctor output formats, exit codes, or whether it is suitable for automated CI checks.;The README does not specify supported Node.js or Portal CLI versions.
It depends During on-call work, I need to inspect service ownership, health, and incidents, and occasionally invoke Portal actions. I want help, previews, dry-runs, and confirmation before execution. Is this workflow suitable for production troubleshooting?
For: An on-call engineer responsible for troubleshooting Spotify internal services and executing Portal actions under controlled permissions

It depends. The plugin is suitable for combining read-only troubleshooting with guarded action invocation, but its safeguards should not be treated as production authorization.

  • doctor performs read-only diagnostics for the plugin, CLI, authentication state, and action readiness.
  • service provides ownership, health, incident, and documentation context before investigation.
  • actions supports discovery, inspection, help, preview, dry-run, and confirmation before invocation, reducing the chance of accidental agent actions.
  • The README does not list the available actions, permission model, rollback behavior, or whether dry-run results exactly match real execution. Production suitability therefore depends on the specific action and Portal authorization configuration.
  • Highlights: Run read-only diagnostics to verify plugin, CLI, authentication, and action readiness.
  • Highlights: Discover and safely invoke Portal actions with built-in help, dry-run, and confirmation safeguards.
  • Workflows: `actions` | Discover, inspect, preview, and safely invoke Portal actions
Not stated in the README:The README does not list actions, their side effects, rollback mechanisms, or permission granularity.;The README does not say whether confirmation covers all risks from agent-generated parameters.
Yes My team standardizes on Cursor and can install internal plugins only from the Cursor team marketplace. I need to make Spotify Portal available in developers' coding environments. Does this project fit that constraint?
For: An engineering productivity lead managing Spotify internal plugins through the Cursor team marketplace

Yes, provided that you can administer the Cursor team marketplace. The README gives a repository-registration and plugin-installation path and does not require manually installing the agent plugin on every machine.

  • Cursor users must register spotify/portal-ai-plugins in their Cursor team marketplace.
  • They then install Spotify Portal from Cursor Settings → Plugins.
  • The plugin still invokes the upstream CLI through npx @spotify/portal-cli <command>, so the team environment needs Node.js, npx, network access, and Spotify Portal authentication.
  • The README does not describe marketplace approval, version pinning, staged rollout, or rollback capabilities, so those organizational controls must come from the team platform setup.
  • Installation / Cursor: Register the `spotify/portal-ai-plugins` repository in your Cursor team marketplace
  • Installation / Cursor: install Spotify Portal from **Cursor Settings → Plugins**
  • Portal CLI: The workflows invoke the upstream CLI through `npx @spotify/portal-cli <command>`
Not stated in the README:The README does not say whether the Cursor team marketplace supports pinning commits, plugin versions, or approval workflows.;The README does not explain how Portal CLI authentication and enterprise network proxies are configured in Cursor.

✨ Highlights

  • Supports three coding agents: Claude Code, Codex, and Cursor
  • Portal CLI provides workflows such as search and service
  • The actions workflow includes help, dry-run, and confirmation safeguards
  • shunt can delegate Claude Code I/O-heavy work to AiKA

🔧 Engineering

  • setup configures Portal CLI authentication and checks five commands including auth
  • doctor runs read-only diagnostics for plugin, CLI, and authentication readiness
  • search queries the software catalog and technical documentation in natural language
  • service generates briefings with owner, health, and incident information
  • actions supports discovering, previewing, and safely invoking Portal actions

⚠️ Risks

  • The repository has 2 contributors, 6 recent commits, and no releases
  • setup requires Portal CLI commands including auth and actions to be available
  • shunt currently supports only Claude Code, not Codex or Cursor
  • Cursor installation requires team marketplace registration and installation from Settings

👥 For who?

  • Spotify Portal users working with Claude Code, Codex, or Cursor
  • Coding-agent teams that need software catalog and technical documentation search
  • Engineers who want service to summarize owner, health, and incident information