# Shortcuts Playground validates on every file write and signs the result, and it needs a Mac with Python 3.10 > A Claude Code and Codex plugin that generates Apple Shortcuts XML, validates it through a self correcting loop hooked into every file write, and signs it with Apple's own shortcuts command line tool, shipping two host specific package trees and static catalogs so that the newest action coverage does not require the newest operating system. **viticci/shortcuts-playground-plugin** — Shortcuts Playground: A Claude Code and Codex plugin for building, validating, signing, and remixing macOS/iOS Shortcuts with natural language. - Repository: https://github.com/viticci/shortcuts-playground-plugin - Website: https://www.macstories.net/shortcuts/ - Stars: 1,134 · Forks: 62 - Language: Python - License: MIT - Published: 2026-09-15 · Updated: 2026-09-15 · Language: en - Canonical page: https://hysenlabs.com/projects/viticci-shortcuts-playground-plugin ## Two plugin trees and two marketplace manifests from one repository The repository is unusually small at the top level: .agents/, .claude-plugin/, .gitignore, LICENSE, README.md, claude/, codex/ and tests/. Nine entries, and three of them carry the entire plugin. That split is the design. One repository produces two packages, one per host, and each host has its own marketplace manifest. Claude Code installs through .claude-plugin/, while Codex reads a marketplace file at .agents/plugins/marketplace.json that points at the Codex package in `./codex`. The install commands differ accordingly. For Claude Code it is two commands from any directory: ```bash claude plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin claude plugin install shortcuts-playground@shortcuts-playground ``` For Codex it is a marketplace registration followed by an interactive browser: ```bash codex plugin marketplace add https://github.com/viticci/shortcuts-playground-plugin codex ``` Inside Codex you then run `/plugins`, pick the Shortcuts Playground marketplace, open the entry and select Install plugin. For local work from a checkout you register the directory instead of the URL, with an absolute path. Both hosts need a new session or thread before the plugin is loaded, which is a step people miss. Claude Code clones the repository into its plugin cache on first install, and the troubleshooting note is specific: if that clone fails with a GitHub auth error, make sure a plain `git clone` of the repository works in your terminal first. ## Signing needs a Mac, and the system Python on older releases is 3.9 Three requirements are listed, and two of them are about the machine rather than the agent. macOS is first because the signing step uses the built-in `shortcuts` command line tool, which the file describes as macOS only. That is the hard constraint. The project advertises macOS and iOS Shortcuts, but the documented path to a signed file runs through a Mac, and no alternative signer is described. Python is the second, and it comes with a trap spelled out in the same paragraph. The bundled validator requires 3.10 or later. The system Python on older macOS versions ships 3.9 and will fail. The two remedies given are installing a newer one through Homebrew with `brew install python3`, or setting `SHORTCUTS_PLAYGROUND_PYTHON` to point at an interpreter you already have. The third requirement is Claude Code or Codex, either the desktop apps or the command line tools. So the practical shape is narrower than the feature list suggests: a Mac, a Python that is not the system one, and one of two agents. The override environment variable is worth knowing about, because it is the difference between the tool working on first run on an older Mac and not working at all. Underneath all of it sits a format constraint. Shortcuts have always been XML files that get signed and encrypted into an Apple only `.shortcut` format, so anything producing an importable file has to go through both halves. ## The Craig Loop is a hook on every file write, and on Codex it is opt-in Validation is the mechanism the project is built around, and it works by being automatic rather than optional. Claude Code runs a `PostToolUse` hook on every file write. When validation fails, the errors feed back into the agent's context so it can fix them before signing, and the file calls that a Craig Loop. The described cost is a few seconds of latency, and the described benefit is a large improvement in output quality. Note what the hook is attached to: every file write, not only the shortcut file. That is what makes the loop self correcting, and it is also why the latency is per write rather than per shortcut. On Codex the same loop is conditional. It works when Codex plugin hooks are enabled with `[features].plugin_hooks = true`, which means editing `~/.codex/config.toml`, and then reviewing and trusting the hook from `/hooks` if Codex prompts for it. Two extra steps that Claude Code users never take. That asymmetry is the reason the file says the Claude Code version offers a richer experience thanks to dedicated commands and agents. The build and remix commands exist as slash commands, and the validation loop underneath them is already wired. The build path is one command: `/shortcuts-playground:build` followed by a description, and the agent designs the action list, wires variables, picks an icon, validates the XML through the loop, and signs the result. ## OS 27 coverage ships as static JSON and is gated behind an explicit target The newest release extends opt-in support for macOS and iOS 27 while leaving macOS 26 users on the existing validation surface by default. The interesting part is how that coverage is delivered. Action snapshots, parameter catalogs, enum catalogs, trigger metadata and sanitized samples of an exported Apple workflow trigger type all ship as static JSON. They are generated from Apple's local ToolKit, ToolRenderer and WorkflowKit metadata plus maintainer exported shortcut XML, and packaged as JSON specifically so that existing users do not need macOS 27 or private Apple frameworks installed. That is a deliberate decoupling of catalog freshness from host capability, and it has a cost worth naming: the catalogs are snapshots of another platform's metadata, taken by someone with access, rather than something read from the machine at run time. The gate has two spellings. OS 27 only identifiers and parameters require either `target_macos = "27"` or the environment variable `SHORTCUTS_PLAYGROUND_TARGET_MACOS=27`, and the default stays conservative for people on macOS 26. The action coverage added for the new platform is a long list of specific things: Stored Content, Add Item to List, Otherwise If, Get Selected Text, Get What's On Screen, VPN actions, Notes markdown, Safari tab groups, route options, and a set of AppIntent parameter and enum updates. The validator list grew in step, now catching blank fields, wrong input keys, bad enum values, invalid boolean parameters, AppIntent schema typos, conditional wiring errors, and signing and import pitfalls. ## The release notes call the drive, file and folder trigger exports lossy One paragraph of the newest release notes is worth reading closely, because it describes a limitation instead of a feature. The OS 27 automation header catalog includes exported samples for Display and Stage Manager, plus what the notes call conservative coverage for External Drive, File Modified and Folder Changed. Display and Stage Manager have copyable headers. The current Mac drive, file and folder exports are documented as lossy and require manual picker configuration in Shortcuts. So two of the three automation categories in that catalog ship in a form that does not round trip, and the fix is a manual step inside the Shortcuts app after the agent has done its work. That is a different kind of support from the rest of the catalog, and it is the kind of gap that only shows up after you have built something. The same release widens the validator, and those two paragraphs together describe the shape of the project: broad syntactic coverage, with a small number of honest gaps called out in the notes rather than left to be discovered. The knowledge base is the other half of the mechanism. The plugin ships reference material that teaches the agent how Shortcuts actions work, what syntax they use, and how they connect to one another, which is what makes generating the XML a matter of following a documented grammar rather than guessing. ## Remix takes unsigned XML, while build produces a signed file The two commands take different inputs and produce different outputs, and the asymmetry is easy to miss. Remix is given a path to an unsigned `.xml` shortcut file plus a description of what to change. The agent then applies what the file calls a surgical diff, preserving every action, UUID and icon that you did not ask it to touch. Preserving the UUIDs matters more than it sounds: those are the stable identifiers the Shortcuts app uses to recognise an action across edits, so regenerating them turns a modification into a replacement. Build goes the other way. It starts from a sentence and ends with a real, signed `.shortcut` file ready to import into the Shortcuts app, which means the XML was encrypted and signed through Apple's own tooling. That leaves a gap at the boundary. To remix something, you need the unsigned XML, and the visible text does not say how to obtain unsigned XML from a shortcut that already exists in the Shortcuts app. Anyone starting from an existing shortcut has to work that out before the command is usable. The example given for build is short enough to try as written: `/shortcuts-playground:build a shortcut that asks for a city, fetches the current weather, and shows a notification`. ## Releases stopped in mid-June and the tag names are not consistent Three releases are published and they sit close together: 1.1.0 on 2026-06-07, 1.2.0 on 2026-06-14 and 1.2.1 on 2026-06-15. The default branch was last pushed on 2026-06-15, the same day as the newest release, and the repository is not archived. That leaves the project with no commit in the roughly four months since. For a plugin whose entire value is a catalog of operating system actions, that gap is the number to watch, because catalogs go stale when the platform moves and nothing in the repository changes. The release names are also inconsistent with each other and with the file. The first two are titled with the product name in front, Shortcuts Playground 1.2.1 and Shortcuts Playground 1.2.0, while the third is titled with a bare 1.1.0. The tags themselves carry no version prefix, yet the file refers to the current release as v1.2.1. None of that breaks anything, but it does mean version strings have to be matched by hand rather than by pattern. The project is by Federico Viticci, and the homepage in the repository metadata points at MacStories rather than at a documentation site, with the introduction linked from there. There is no docs directory in the tree: the knowledge base ships inside the plugin packages. ## Conclusion Shortcuts Playground suits someone on a Mac who wants to describe a Shortcut in English and get back an importable file, and who is willing to accept a Mac only signing step as the price. Four things to check first. The system Python on older macOS releases is 3.9 and the bundled validator will fail on it. Automatic validation is free on Claude Code and gated behind a config flag plus a trust prompt on Codex, which is the real reason the Claude Code path is described as richer. The OS 27 action coverage is static JSON you must opt into with an explicit target. And the drive, file and folder trigger exports are described by the project's own notes as lossy. ## FAQ ### What does Shortcuts Playground need in order to run? macOS, because signing uses the built-in shortcuts command line tool, which is macOS only. Claude Code or Codex, either the desktop app or the command line tool. And Python 3.10 or later, because the bundled validator requires it, while the system Python on older macOS versions ships 3.9 and fails. Install a newer one with brew install python3 or point SHORTCUTS_PLAYGROUND_PYTHON at your interpreter. ### How does Shortcuts Playground check the shortcut it generated? Claude Code runs a PostToolUse hook on every file write, and validation errors feed back into the agent's context so it can correct them before signing, in a loop the project calls a Craig Loop. It adds a few seconds of latency. On Codex the same loop needs plugin hooks enabled with [features].plugin_hooks = true and the hook trusted from /hooks. ### Do I need macOS 27 installed to use the newest Shortcuts Playground features? No. The macOS and iOS 27 coverage ships as static JSON catalogs generated from Apple's local metadata and maintainer exported shortcut XML, so users do not need macOS 27 or private Apple frameworks. Using OS 27 only identifiers requires opting in with target_macos set to 27 or SHORTCUTS_PLAYGROUND_TARGET_MACOS=27, and the default stays conservative for macOS 26 users. ### How do I remix a shortcut that already exists? Run /shortcuts-playground:remix with a path to an unsigned .xml shortcut file and a description of the change, and the agent applies a surgical diff that preserves every action, UUID and icon you did not ask it to touch. Note that the input is unsigned XML, not a signed .shortcut file, and the documentation does not cover producing that XML from an existing shortcut. ### How do I install Shortcuts Playground in Codex? Run codex plugin marketplace add with the repository URL, then start codex, run /plugins, choose the Shortcuts Playground marketplace and install. The repository carries a Codex marketplace at .agents/plugins/marketplace.json pointing at the package in ./codex, and a checkout can be registered by absolute path instead. Automatic validation needs [features].plugin_hooks = true in ~/.codex/config.toml. ## Sources - [License: MIT](https://github.com/viticci/shortcuts-playground-plugin/blob/main/LICENSE) - [Project website](https://www.macstories.net/shortcuts/) - [README](https://github.com/viticci/shortcuts-playground-plugin/blob/main/README.md) - [Releases](https://github.com/viticci/shortcuts-playground-plugin/releases) - [viticci/shortcuts-playground-plugin on GitHub](https://github.com/viticci/shortcuts-playground-plugin) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/viticci-shortcuts-playground-plugin