Potlane

Parallel MCP lanes for Penpot, under one user account.

Distribution: potlane on npm · Chrome extension ZIP and release notes · Chrome Web Store listing

Potlane lets an orchestrator run multiple AI agents against independent Penpot tabs without creating extra Penpot users or patching Penpot. A local MCP gateway routes each official Penpot tool call through a named lane; the Chrome extension owns the matching browser tab and official plugin instance.

What you get

• One MCP endpoint for any number of agent lanes.

• One signed-in Penpot account shared by all lanes.

• Strict one-lane-to-one-tab binding with a fresh private routing token on every rebind.

• Serial execution inside one lane and real parallel execution across different lanes.

• Automatic background tab provisioning and safe plugin reconnect after extension or browser reload.

• Confirmed cleanup of one idle lane or all idle lanes from the side panel.

• Durable cleanup intent when one managed tab is closed; full-window restore remains safe.

• Quarantine for ambiguous, timed-out, or partially applied mutations, with no automatic mutation retry.

• Secret-safe local audit events, strict request validation, bounded sessions, and loopback-only networking.

The current release was validated against self-hosted Penpot 2.17.0-RC5 with three independent agent workloads, retained design pages, and measured concurrent execution. Read the real end-to-end evidence.

Extension preview

The release preview renders the real side-panel component and production styles with deterministic demo state. The Support, Dashboard, and Pricing cards are actual exports retained from the three-agent E2E run.

How it works

flowchart LR
    A1["Agent 1"] -->|"lane A"| G["Potlane gateway"]
    A2["Agent 2"] -->|"lane B"| G
    A3["Agent 3"] -->|"lane C"| G
    G -->|"private token A"| R["Official Penpot MCP router"]
    G -->|"private token B"| R
    G -->|"private token C"| R
    R <-->|"plugin WebSocket A"| T1["Penpot tab A"]
    R <-->|"plugin WebSocket B"| T2["Penpot tab B"]
    R <-->|"plugin WebSocket C"| T3["Penpot tab C"]
    E["Potlane Chrome extension"] --> T1
    E --> T2
    E --> T3

The extension is required because it owns tabs and visible official plugin iframes. The gateway is required because a Manifest V3 extension cannot expose the localhost MCP HTTP endpoint expected by agent clients. Docker and a Penpot fork are not required.

Inside one lane, calls are queued because Penpot plugin code runs in mutable tab-local state. Different lanes have independent queues, so they can execute simultaneously. The gateway persists an in-flight mutation before dispatch; any ambiguous result quarantines that lane until a human- or agent-verified reconciliation.

Install

Requirements:

• Node.js 22.23+ (Node.js 24 LTS recommended)

• Chrome 114+

• Penpot 2.17+ with the official MCP service enabled in multi-user mode

1. Start the gateway

npx potlane

The gateway listens only on 127.0.0.1:4711 by default. On startup it writes a ready-to-use private orchestrator configuration to the mcp.json path printed in the terminal. The file is mode 0600 and lives beside runtime state in .potlane/.

Run npx potlane --help to see the supported environment variables. Keep the gateway terminal open while agents use Potlane.

2. Install the Chrome extension

Install Potlane from the Chrome Web Store, then pin it and open its side panel.

For an unreleased development build:

git clone https://github.com/webcredo/potlane.git
cd potlane
corepack enable
pnpm install --frozen-lockfile
pnpm build

Open chrome://extensions, enable Developer mode, choose Load unpacked, and select apps/extension/.output/chrome-mv3.

3. Complete the one-time Penpot setup

1. Disable Penpot's built-in single-tab MCP connection.

2. In a Penpot workspace, open Plugins and install the official manifest: http://localhost:9001/plugins/mcp/manifest.json.

3. Give the official plugin the requested permissions. Penpot stores that install for the signed-in user, not once per project.

4. Add the generated private mcp.json to Codex, Claude, or another MCP orchestrator.

Potlane can detect whether the official plugin is installed, but it cannot silently grant plugin permissions. That one-time confirmation remains a user action.

4. Create lanes through MCP

Ask the orchestrator to call potlane_create_lane for every independent task. New MCP-created lanes carry automatic provisioning intent: Potlane creates a dedicated background Penpot tab, opens the installed official plugin, rotates a private routing token, and brings the lane to ready without side-panel interaction.

The main orchestrator endpoint owns lane creation, selection, pause, recovery, and scope updates. If separate agent processes need hard lane-level capabilities, obtain each agent's config from the authenticated GET /api/lanes/:id/mcp-config endpoint. That scoped endpoint cannot list, select, pause, rebind, or call tools in another lane.

Every generated MCP configuration contains a local bearer token. Treat it like a password and never commit it, paste it into issues, or include it in screenshots.

Lane cleanup and recovery

• Closing one Potlane-managed tab records durable deletion intent. The lane is deleted as soon as it is idle, including after a temporary gateway outage.

• Closing an entire Chrome window preserves lanes so Chrome session restore can reconnect them.

• A live replacement binding cancels stale deletion intent.

• The side panel can delete one lane or all lanes only after an explicit confirmation.

• Busy, in-flight, uncertain, or recovery lanes are never deleted by browser cleanup.

• A failed mutation is never retried automatically. Inspect the design, replace the old tab/plugin execution context, and explicitly reconcile the quarantined lane.

This behavior prevents both immortal agent lanes and unsafe cleanup of work that may still be running.

Developer setup

Potlane is a pnpm monorepo:

Start both development processes:

corepack enable
pnpm install --frozen-lockfile
pnpm dev

WXT writes the unpacked extension to apps/extension/.output/chrome-mv3. After background/content-script changes, use Reload on chrome://extensions; after side-panel-only changes, reopening the panel is often enough. Keep the gateway in a separate terminal so its logs remain visible.

pnpm package:extension creates the Chrome Web Store artifact in an isolated production output. The resulting ZIP does not contain the local manifest key; the unpacked development output keeps that public key so its extension ID remains stable between rebuilds.

Before opening a pull request:

pnpm verify                    # formatting/lint, strict types, unit tests, production builds
pnpm test:integration:penpot   # real local Penpot router + mock plugin sockets
pnpm package:extension         # Chrome Web Store zip
pnpm --filter potlane pack     # npm tarball

Unit tests never require Docker, Chrome, or a live Penpot. The integration harness requires the local Penpot MCP service but does not edit a real design. Manual release validation is documented in docs/development.md.

When changing lifecycle code, preserve these invariants:

• one active binding per lane and one lane per managed tab;

• status reports must match both the bound tab ID and token generation;

• no automatic retry after a mutation may have reached the plugin;

• no deletion while work is busy, in-flight, uncertain, or recovering;

• no credentials, tool arguments, code, results, or raw private URLs in audit events.

Read CONTRIBUTING.md before your first change. Pull requests should explain the user-visible result, routing/lifecycle risk, test evidence, and any Penpot upstream behavior they depend on.

Security and boundaries

Potlane isolates execution contexts and routing, not Penpot permissions. Every lane still acts as the same signed-in user. Scope declarations are coordination warnings, not a security sandbox; agents can conflict if they intentionally edit the same Penpot object.

The gateway binds to loopback, protects MCP with a random local bearer secret, validates the exact Chrome extension request shape, and never returns gateway or lane secrets in public state. Local state, generated MCP configs, and audit logs are written under .potlane/ and must remain private. See SECURITY.md for the threat model and private reporting instructions.

Documentation

• Architecture and lifecycle

• Developer and release guide

• Penpot compatibility contract

• Real three-agent E2E evidence

• Privacy policy

• Chrome Web Store listing copy

• Changelog

Support the project

If Potlane saves you time, you can support continued maintenance on Ko-fi:

Contributions, reproducible bug reports, and careful compatibility testing are equally valuable.

Apache License 2.0. See LICENSE.