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.‎

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.

• 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.

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.

1. Open Claude for Mac and start a new Claude Code session (the terminal panel at the bottom).
2. 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
   

3. Start a new session to load the plugin.

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

Register the marketplace, then install the plugin from Codex's plugin browser:

# 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

1. Open the Codex app and make sure you're signed in.
2. Register the marketplace once from Terminal:

   codex plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin
   

3. Open Plugins in the Codex app, switch to the Shortcuts Playground marketplace, open Shortcuts Playground, and click the plus button or Add to Codex.
4. To enable automatic validation, add [features].plugin_hooks = true to ~/.codex/config.toml, then review/trust the hook from /hooks if Codex prompts for it.
5. Start a new thread to load the plugin.

/shortcuts-playground:build a shortcut that asks for a city, fetches the current weather, and shows a notification

Or just describe what you want in natural language — Claude's skill auto-invocation will pick up the intent:

Build me a shortcut that takes my 5 most recent screenshots and sends them to a contact on iMessage

When it's done, open the signed .shortcut file from ~/Documents/Shortcuts Playground/ in Finder. Shortcuts.app will offer to import it.

Point it at an unsigned .xml file and describe the change:

/shortcuts-playground:remix /Users/you/Documents/Shortcuts Playground/drafts/Weather.xml add a notification at the start saying "Fetching weather…"

The remix preserves everything you didn't ask to change. Your original file is never overwritten.

Shortcuts Playground can take you roughly 90% of the way to a complete, functioning shortcut. The remaining 10% should be checked and refined by you. In testing, it was able to one-shot dozens of simple shortcuts using Apple's built-in actions, as well as complex shortcuts involving web APIs, advanced logic, SSH, shell scripting, and more.

Common things to watch for:

• Variables. Occasionally a field will be empty where a variable connection is needed. You'll need to go in there and manually connect that variable or parameter yourself.
• Repeat loops. Double-check the wiring inside loops: variable scope can get tricky.
• Always inspect the result. Open the shortcut in the Shortcuts app and walk through it before relying on it. This is good friction: you'll learn a lot about how shortcuts work from the inside.

For best results, use Claude Opus 4.6/4.7 or GPT 5.5 as the underlying models. Higher reasoning efforts produce better outputs, but introduce latency.

By default, shortcuts are saved to ~/Documents/Shortcuts Playground/:

~/Documents/Shortcuts Playground/
├── My Shortcut.shortcut          # signed file — open to import
├── drafts/
│   └── My Shortcut.xml           # working unsigned draft
└── 2026-05-09/
    └── My Shortcut-151223.xml    # dated archive

To change the output directory, edit ~/.claude/settings.json:

{
  "pluginConfigs": {
    "shortcuts-playground@shortcuts-playground": {
      "options": {
        "output_dir": "/Users/you/Documents/Shortcuts Playground"
      }
    }
  }
}

The plugin also supports a signing_mode option (anyone for public distribution, people-who-know-me for contacts only). Default is anyone.

A companion Shortcuts Playground Remote shortcut that communicates with Claude Code and Codex over SSH – letting you generate shortcuts from iPhone and iPad – is available exclusively for Club MacStories members.

claude plugin update shortcuts-playground@shortcuts-playground

Start a new Claude Code session after updating to pick up changes to agents and hooks.

claude plugin uninstall shortcuts-playground@shortcuts-playground
claude plugin marketplace remove shortcuts-playground

Your ~/Documents/Shortcuts Playground/ directory stays intact.

This repository ships plugins for two agent runtimes:

The root .claude-plugin/marketplace.json installs the Claude Code plugin from ./claude. The root .agents/plugins/marketplace.json installs the Codex plugin from ./codex.

For detailed technical documentation, see claude/README.md and claude/INSTALL.md.

by Federico Viticci, MacStories.net

MIT.