core

name	core
description	Core Tinker CLI usage guide. Read this before running any tinker commands. Covers discovering installed plugins, opening and closing plugin windows, listing running plugins, and controlling the Tinker desktop app from the command line. Use when the user asks to open a Tinker plugin, list plugins, check what is running, restart or close a plugin, or quit Tinker.
allowed-tools	Bash(tinker:*)

Tinker core

Tinker is a desktop toolbox built on Electron. Each tool is a plugin (for example JSON Editor, RegExp tester). The tinker CLI talks to the running Tinker app over a local IPC socket, so agents can open plugins and inspect what is running without clicking the UI.

If Tinker is not running, the CLI auto-launches it and retries the command.

For calling plugin MCP tools or wiring plugins into MCP clients, load the mcp skill after the basics here.

The core loop

tinker list          # 1. See installed plugins
tinker open <plugin> # 2. Open a plugin window
tinker ps            # 3. Confirm it is running
tinker close <plugin> # 4. Close when done

Plugin names accept the short form (json-editor) or the full id (tinker-json-editor). The CLI normalizes to tinker-<name> automatically.

Scoped npm plugins (e.g. @tencent/tinker-wxapkg) appear in tinker list as ids like tencent-tinker-wxapkg. For those, use the full id from list (or the @scope/... package name) — short names such as wxapkg will not resolve.

Quickstart

tinker list
tinker open json-editor
tinker ps
tinker close json-editor

list output tags plugins as [builtin], [mcp], and [background] when applicable. [background] means Run in Background is enabled (required for tinker open --headless). Plugins marked [mcp] expose programmatic tools; see the mcp skill for tools, call, and mcp commands.

Prerequisites

• Tinker app must be installed. The CLI ships with the app (tinker on macOS/Linux/Windows).
• Most commands need the main Tinker process. The CLI connects to a Unix socket (macOS/Linux) or named pipe (Windows). Connection errors usually mean Tinker is still starting; wait a moment and retry.

Discovering plugins

tinker list

Example output:

  tinker-json-editor [builtin] [mcp] - JSON editor with text and tree modes
  tinker-regexp [builtin] [mcp] - Regular expression tester
  tinker-hash [builtin] - Hash calculator

Use the id column (tinker-json-editor) or the short name without the prefix (json-editor) in other commands.

Plugin lifecycle

tinker open <plugin>                              # open in a detached window
tinker open <plugin> --headless                   # open in background (no window)
tinker open <plugin> --remote-debugging-port 9222   # auto-launch Tinker with CDP (when app was not running)
tinker close <plugin>                               # close a running plugin
tinker restart <plugin>                             # close then open (starts if not running)
tinker quit                                         # quit the Tinker app

open and restart succeed even when the plugin was not running. close fails if the plugin is not running.

--headless starts the plugin without a window. The plugin must already have Run in Background enabled in Tinker (right-click the plugin → checkbox); otherwise open fails.

ps lists running plugins with renderer process IDs:

tinker ps

  tinker-json-editor 12345

Common workflows

Open a plugin for the user

tinker list
tinker open <plugin>
tinker ps

Restart a stuck plugin

tinker restart <plugin>
tinker ps

Command reference

Command	Description
tinker list	List installed plugins
tinker ps	List running plugins with PIDs
tinker open <plugin>	Open a plugin window
tinker open <plugin> --headless	Open a plugin in the background (no window)
tinker close <plugin>	Close a running plugin
tinker restart <plugin>	Restart a plugin
tinker quit	Quit Tinker

When to load another skill

• Create a standalone plugin (clone template, npm link, local dev): load the create skill.
• Plugin MCP tools (tools, call, mcp, MCP client integration): load the mcp skill.

Troubleshooting

Failed to connect to Tinker — Tinker is not running and auto-launch may have failed. Start the Tinker app manually, then retry.

Plugin not found: tinker-... — Run tinker list and use a valid id or short name. External plugins are installed globally with the tinker- npm prefix.

Plugin is not running: tinker-... — Run tinker open <plugin> before close.

Plugin does not allow running in background: tinker-... — Enable Run in Background for the plugin in Tinker before using tinker open --headless.

Connection timed out — Tinker may still be starting after auto-launch. Wait a few seconds and retry.

Working safely

• CLI commands affect the user's live Tinker session and open plugin windows on their desktop.
• Confirm the target plugin with tinker list before opening or restarting.
• For programmatic plugin manipulation, load the mcp skill and follow its safety notes.