Name: shortcuts-playground
Author: viticci

Shortcuts Playground

Create Apple Shortcuts with natural language using Claude Code or Codex.

Shortcuts Playground is a plugin for Claude Code and Codex that lets you turn any idea into a shortcut for Apple's Shortcuts app. Describe what you want in plain English; a few minutes later, you get a real, signed .shortcut file ready to import into the Shortcuts app.

Under the hood, shortcuts have always been XML files that get signed and encrypted into a special, Apple-only .shortcut format. Shortcuts Playground ships a comprehensive knowledge base that teaches Claude and Codex how Shortcuts actions work, what syntax they use, and how they connect to one another. Agents generate the XML, validate it through a loop, and sign it using Apple's native shortcuts CLI.

The result is a valid shortcut, built from a sentence.

A project by Federico Viticci. Read more here.‎

What It Does

You can install Shortcuts Playground in either Claude Code or Codex. At the moment, the Claude Code version of the plugin offers a richer experience thanks to dedicated commands and agents.

Build from scratch. In Claude Code, type /shortcuts-playground:build followed by a description of the shortcut you want. Claude designs the action list, wires variables, picks an icon, validates the XML through a self-correcting loop, and signs the result.
Remix an existing shortcut. Type /shortcuts-playground:remix with a path to an unsigned .xml shortcut file and describe what to change. The agent applies a surgical diff — preserving every action, UUID, and icon you didn't ask to touch.
Automatic validation. Claude Code runs a PostToolUse hook on every file write. Codex can do the same when Codex plugin hooks are enabled with [features].plugin_hooks = true. Errors feed back into the agent's context so it can fix them before signing. This is called a Craig Loop. It adds a few seconds of latency but dramatically improves output quality.

Requirements

macOS. The signing step uses the built-in shortcuts CLI, which is macOS-only.
Claude Code or Codex. Install from claude.com/claude-code or openai.com/codex. Either the desktop apps or CLIs will work.
Python 3.10+. The bundled validator requires 3.10 or later. The system Python on older macOS versions ships 3.9 and will fail. Install a newer version via Homebrew (brew install python3) or set SHORTCUTS_PLAYGROUND_PYTHON to point at your interpreter.

Installation in Claude

In the terminal

Two commands. Run them from any directory:

# 1. Register the marketplace
claude plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin

# 2. Install the plugin
claude plugin install shortcuts-playground@shortcuts-playground

Claude Code clones the repository into its plugin cache on first install. If the clone fails with a GitHub auth error, make sure git clone https://github.com/viticci/shortcuts-playground-plugin.git works in your terminal first.

In the Claude for Mac app

Open Claude for Mac and start a new Claude Code session (the terminal panel at the bottom).

Click the terminal input area and run the same two commands:

claude plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin
claude plugin install shortcuts-playground@shortcuts-playground

Start a new session to load the plugin.

Installation in Codex

Codex installs plugins from marketplaces. This repository includes a Codex marketplace at .agents/plugins/marketplace.json, which points at the Codex package in ./codex.

In the terminal

# 1. Register the marketplace
codex plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin

# 2. Open Codex
codex

Inside Codex, type /plugins, choose the Shortcuts Playground marketplace, open Shortcuts Playground, and select Install plugin. Start a new session to load the plugin.

For local development from a cloned checkout, register the checkout instead of GitHub:

codex plugin marketplace add /absolute/path/to/shortcuts-playground-plugin

In the Codex app