penpot-axi

penpot-axi lets a coding agent inspect, read, export, and script the Penpot design already open in your browser. It wraps the raw Penpot MCP tools in focused commands with compact TOON output, so routine design work starts from the file instead of hand-written Plugin API boilerplate.

The named commands are for reading and navigation. exec remains the open-ended path for creating or editing a design through the Penpot Plugin API.

Start here

You need: Node.js 20+, a Penpot file open in your browser, and the Penpot MCP plugin connected to that live file. There is no offline mode.

1. Run the dashboard

npx -y penpot-axi

The CLI discovers the connected MCP endpoint and its rotating session token from ~/.claude.json. To use another endpoint, append --url <mcp-url> to the command or set PENPOT_MCP_URL.

When the connection is ready, the dashboard reports the active page, page list, current selection, and next commands. A NOT_CONNECTED response means Penpot or its MCP plugin is not connected yet.

2. Inspect before changing anything

# Read a page's hierarchy. Quote page names containing spaces.
npx -y penpot-axi tree "Screens" --depth 2

# Find likely targets without loading the whole file into context.
npx -y penpot-axi find --type board --page "Screens"

# Read just the fields you need from a known shape.
npx -y penpot-axi get <shape-id> --props fills,x,y,width,height

3. Use the raw Plugin API only when you need it

# Your code must return data. Do not console.log returned values.
npx -y penpot-axi exec -e "return penpot.selection.map(s => s.name);"

For repeated local use, install it globally with npm install -g penpot-axi and drop npx -y from the examples.

The workflow

Penpot remains the source of truth. penpot-axi provides a small control surface around the file the user currently has open:

dashboard -> find the page or shape -> inspect only needed data -> export or script -> verify

Run penpot-axi <command> --help for exact syntax. The default output is TOON; css and markup intentionally print raw code.

Pick an interface

Agent skill

The repository includes an ambient penpot-axi skill for compatible coding agents:

npx skills add rhyumiranda/penpot-axi

It directs the agent to use the CLI when a task touches a connected Penpot file. penpot-axi setup hooks can add the dashboard to supported agents' new sessions.

Why this wrapper exists

The Penpot MCP exposes powerful general tools: execute_code, penpot_api_info, and export_shape. For common reads, that means an agent repeatedly discovers the API, writes Plugin API JavaScript, and parses broad JSON responses.

penpot-axi packages frequent reads into commands, projects fields where practical, and returns compact TOON tables. It does not replace the Plugin API: use exec whenever the command map does not cover the work.

Measured token cost

The included benchmark compares both paths against the same connected five-page Penpot file with more than 2,300 shapes. It measures context tokens using the cl100k_base tokenizer; it does not run an LLM or claim task-success or dollar savings.

The large find difference comes from a deliberate default: raw MCP returns every match while penpot-axi caps results at 50 and reports the real total. Without that outlier, the measured routine reads still use about 60% fewer tokens.

Reproduce the benchmark with node scripts/bench.mjs. It needs a connected live file with a Screens page and at least one board, as used by the harness.

Connection model

agent or shell
      |
      v
penpot-axi ---- HTTP MCP endpoint ---- Penpot MCP service ---- Plugin API ---- browser tab

The MCP URL and session token rotate with the connected session. penpot-axi discovers them rather than hardcoding credentials.

Troubleshooting

Limits

• The CLI works only with a connected live Penpot file.
• The Plugin API is the write path; named commands intentionally focus on common reads and exports.
• Exporting an entire page can fail. Export a concrete shape or group instead.

Development

pnpm install
pnpm build
node scripts/spike.mjs

spike.mjs is a live end-to-end smoke test, so it needs the Penpot MCP connection.

License

MIT Copyright 2026 Rhyu Miranda