penpot/docs/technical-guide/developer/agentic-devenv.md

title, desc

title	desc
3.11. Agentic Development Environment	Dive into agentic Penpot development.

Agentic Development Environment

The agentic DevEnv is an extension of the standard DevEnv (the general DevEnv instructions apply), optimised for AI agent-based development. It adds MCP servers (Penpot, Serena, Playwright) and supports a launcher that wires them into your AI client.

Two things to know up front:

• Parallel workspaces are first-class. Run several devenv instances side by side - one per AI agent if you like - each with its own source-tree clone, ports, and tmux session. Pass --ws N to target one.
• Your existing AI-client config is preserved. The launcher loads a per-workspace MCP config on top of your global one.

Quick Start

1. Bring up one or more workspaces¹:

   ./manage.sh run-devenv-agentic              # ws0 (the live repo)
   ./manage.sh run-devenv-agentic --ws 1       # ws1 (sibling clone)
   

   Add --ws 2, --ws 3, … for more parallel workspaces.

2. Launch a browser with remote debugging enabled:

   For example, with Chrome:

   google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"
   

3. Open Penpot in that browser:

   • ws0: https://localhost:3449
   • ws1: https://localhost:13449
   • etc. (ports are offset by 10000 × N for wsN)

   On first login per account, open settings → Integrations and toggle "MCP Server" on. The agentic DevEnv runs the MCP server in single-user mode - the key and proxied URL shown in the UI are not needed.

4. Launch your AI client against the workspace you want it to drive:

   ./manage.sh start-coding-agent claude              # ws0
   ./manage.sh start-coding-agent claude --ws 1       # ws1
   

   Supported clients: claude | opencode | vscode | codex.

5. Attach to the tmux session for the workspace (optional):

   ./manage.sh attach-devenv            # ws0
   ./manage.sh attach-devenv --ws 1     # ws1
   

6. Shut down workspaces with ./manage.sh stop-devenv, either one by one or all at once. You cannot shut down ws0 if any other workspace is still running, since it's the worker-bearer. Shared infrastructure will be cleaned up when the last workspace is stopped.

Optional: watch Serena's activity in its dashboard (http://localhost:14182 for ws0, http://localhost:24182 for ws1, etc.).

Capabilities

The agentic DevEnv leverages several MCP servers in order to provide AI agents with a comprehensive toolbox for Penpot development:

• Penpot MCP Server provides tools for directly interacting with a live Penpot instance, enabling the agent to
  • execute JavaScript code in the frontend (using the plugin API),
  • execute ClojureScript code in the frontend (REPL),
  • import .penpot files for reproducing issues,
  • export design elements as images, and more.
• Serena MCP Server provides code intelligence tools with support for Clojure and TypeScript. Its memory system is used to organise project knowledge in a context-efficient manner.
• Playwright MCP Server provides tools for browser remote control.

Equipped with the tools provided by these MCP servers, the agent can fully close the development loop, i.e. it can ...

• retrieve information on an issue from GitHub,
• import relevant design files for reproduction,
• execute JavaScript and ClojureScript code directly in Penpot in order to
  • simulate user interactions (e.g. to reproduce an issue),
  • test hypotheses on the root cause of an issue, and
  • experiment with implementations before touching the actual codebase,
• detect, analyse and recover from crashes in the frontend,
• make code changes (using IDE-like symbolic operations)
• test the changes in the live Penpot instance, and
• create commits and PRs resolving the issue.

The flow in detail

First-time setup

The MCP frontend flag. Edit frontend/resources/public/js/config.js (create it if missing) and ensure penpotFlags contains enable-mcp:

var penpotFlags = "enable-mcp";

The file is gitignored and lives in the live repo only. On every run-devenv-agentic call it is read directly for ws0; for wsN (N ≥ 1) it is copied into the workspace clone on the initial sync only - subsequent --sync passes leave the workspace's copy alone so per-workspace customisations survive. run-devenv-agentic refuses to start if the file is missing.

Browser remote debugging. The Playwright MCP server drives a real browser instance over the Chrome DevTools protocol. To enable it, launch a Chromium-based browser (Chrome, Vivaldi, Opera, …) with the --remote-debugging-port flag and a separate user-data directory:

google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"

Verify it works by visiting http://127.0.0.1:9222/json/version. If you change the port, update the Playwright MCP entry in .devenv/shared/*.json accordingly. For security reasons, do not enable remote debugging on the profile you use for regular browsing.

Enable the MCP integration in Penpot. The Penpot UI has a per-account MCP toggle. After logging into your Penpot instance at https://localhost:3449, open account settings, click "Integrations" in the sidebar, and enable the "MCP Server" toggle. The agentic DevEnv runs the MCP server in single-user mode, so the generated key and proxied URL printed in the UI are not needed - only the toggle itself matters.

(Optional) custom devenv image. Only needed if you want to modify the devenv image itself (add a tool, change a base layer):

./manage.sh build-devenv --local

The default run-devenv-agentic flow pulls the published image automatically, so regular users never run this.

Bringing up workspaces

./manage.sh run-devenv-agentic \
    [--ws N] [--sync] [--serena-context CTX] \
    [--git-user-name NAME] [--git-user-email EMAIL]

Brings one agentic instance up. Errors out if the target is already running.

--ws N (N ≥ 1) auto-starts ws0 first if it is not already up - ws0 is the worker-bearer and must be running whenever any wsN is. Per-instance ports are offset by 10000 × N (ws1's MCP at http://localhost:14401/mcp, Serena MCP at http://localhost:24181, Serena dashboard at http://localhost:24182, etc.). manage.sh prints the full URL set on every bring-up so you don't compute offsets by hand. See the Dev environment guide for the workspace lifecycle, --sync semantics, and stop ordering.

Git identity for agent commits. Coding agents typically need to commit inside the devenv, so run-devenv-agentic wires a Git identity into the container's global config on every bring-up. By default it propagates the host's effective git config user.{name,email} (local repo override wins over ~/.gitconfig, matching what git commit on the host would record). Override with --git-user-name "Full Name" / --git-user-email you@example.com when you want agent commits to carry an identity different from your normal one. Without either source the script warns and proceeds; commits inside the devenv will fail until you fix it. See the Dev environment guide for the full mechanics.

Note: the MCP and Serena tmux windows are only added when the tmux session is first created. If a workspace was already brought up with ./manage.sh run-devenv (non-agentic), stop it before re-running agentically:

./manage.sh stop-devenv
./manage.sh run-devenv-agentic

Launching an AI client

The agentic environment supports any AI client, one just needs to set the right MCP config, see manual configuration below. For some popular clients, the manage.sh CLI offers direct support through the following mechanism:

Every run-devenv-agentic regenerates three MCP-client config files with the workspace's ports baked in; Codex is wired up at launch instead (see below):

Client	File	Loaded how
Claude Code	<workspace>/.devenv/mcp/claude-code.json	--mcp-config <file> flag
opencode	<workspace>/.devenv/mcp/opencode.json	OPENCODE_CONFIG=<file> env var
VS Code Copilot	<workspace>/.vscode/mcp.json	Auto-discovered when opening the workspace
Codex CLI	(none written)	Injected as -c mcp_servers.… overrides by start-coding-agent codex

The files are committed templates + an envsubst pass; see .devenv/README.md for the full layout.

./manage.sh start-coding-agent <client> [--ws N] [...passthrough] launches the chosen client against one workspace, cd'ing into the right directory and refusing to launch if the instance is not running:

./manage.sh start-coding-agent claude              # ws0
./manage.sh start-coding-agent opencode --ws 1     # ws1
./manage.sh start-coding-agent vscode              # opens VS Code on ws0
./manage.sh start-coding-agent codex --ws 2        # ws2

A given AI client session drives exactly one workspace, so running N parallel workspaces typically means running N AI client sessions, each pointed at a different workspace's ports.

What each launcher does:

• Claude Code is started with --mcp-config .devenv/mcp/claude-code.json, which is additive - your existing global Claude Code MCP entries stay available alongside the three entries we ship (Penpot MCP, Serena MCP, Playwright). To shadow one of our entries with a private one, install it under Claude Code's local scope (claude mcp add --scope local …); local wins over --mcp-config.
• opencode is started with OPENCODE_CONFIG=.devenv/mcp/opencode.json. opencode's precedence chain is global → OPENCODE_CONFIG → project, so the file we generate overrides entries with the same name in your global config. To override our entries in turn, drop a personal opencode.json at the repo root - it's gitignored on purpose.
• VS Code Copilot - code "$workspace" opens VS Code on the workspace. Copilot loads both your user-profile MCP config and the workspace's .vscode/mcp.json. That workspace file is deep-merged rather than overwritten: on ws0 (where it is the live repo's own file) any servers you added survive, and only our three (Penpot MCP, Serena MCP, Playwright) are rewritten to the current ports; on ws1+ it is created from scratch. To shadow one of ours, add a same-named entry in your user profile - it wins.
• Codex CLI - codex is exec'd from the workspace dir with our servers passed as -c mcp_servers.<name>.... overrides built from the committed templates. Nothing is written to .codex/config.toml, so your own project- or user-level Codex config is left untouched (and no "trusted project" prompt is involved for our servers). Because -c is Codex's highest-precedence layer, our entries win over a same-named server in your config; to override one, append your own -c after the client name (... start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"') - the later -c wins.

Manual AI-client configuration

The start-coding-agent launcher covers Claude Code, opencode, VS Code Copilot, and the Codex CLI. For any other client (JetBrains AI Assistant, Claude Desktop, Antigravity, …), or if you prefer to wire things up yourself, configure the MCP servers in your client's native format using the URLs below.

The Penpot and Serena URLs for the workspace you want to target are printed by manage.sh every time it brings an instance up; copy them straight from that output. The mechanical rule is port = base + 10000 × N for wsN, with bases 4401 (Penpot MCP) and 14181 (Serena MCP). Playwright is not workspace-scoped - it connects to your local browser, so the same entry works for every client.

Project-level MCP config files (Claude Code, opencode - manual path)

If you'd rather not go through the launcher, both Claude Code and opencode support project-level MCP config files that merge with the developer's global config:

• Claude Code reads .mcp.json at the project root. Local scope (claude mcp add --scope local …) overrides project scope.
• opencode reads opencode.json at the project root (or any ancestor Git directory). Configs are merged in the order global → OPENCODE_CONFIG → project.

The schemas differ between the two, so a workspace supporting both ships both files. For multi-workspace work, edit the port numbers in each workspace's copy once to match its offset.

Example configuration

Below is a JSON-based configuration snippet in Claude Code's mcpServers schema, targeting ws0 (main), using mcp-remote to wrap HTTP-based servers. To target a different workspace, substitute the Penpot MCP and Serena MCP URLs with the ones for that workspace.

For clients using a different configuration format, extract the relevant information (server URLs or launch commands) and configure the servers appropriately, referring to your client's documentation.

{
  "mcpServers": {
    "penpot-ws0": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:4401/mcp", "--allow-http" ]
    },
    "serena-ws0-devenv": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:14181/mcp", "--allow-http"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
    }
  }
}

Penpot MCP Server

• The URL above connects directly to the server in the DevEnv, which runs in single-user mode. You do not need to use the proxied URL or the user token that is provided by the Penpot UI.

Serena MCP Server

• The matching Serena dashboard lives on the next port (14182 for ws0, 24182 for ws1, …) and is also printed by manage.sh on startup.

Working on Development Tasks

After having made the configuration changes, restart your AI client. The configured MCP servers should now be running and accessible to your client.

The agent's entrypoint for development is an activation of the penpot project with Serena. Start by instructing your agent as follows,

Activate project penpot.

and it should retrieve fundamental project information, expecting further instructions on what to do.

Always start your first prompt with these activation instructions, as this bootstraps the agent's context.

Checking MCP Server Operability

To check if all integrations are working correctly, you can perform a series of tests.

1. Open Penpot in the debugging-enabled browser and open a design file.

2. Ask the agent to activate the project (Serena project activation):

   Activate project penpot.

3. Penpot MCP

   • Checking the connection to the Penpot frontend:

     Get an overview of the current page in Penpot by using the execute_code tool.

   • Checking the ClojureScript REPL:

     Use the cljs_repl tool to check whether the Penpot frontend has crashed.

4. Serena MCP

   • Checking Serena's symbolic tools:

     Use the find_symbol tool to find function locate-shape (cljs) and class PenpotMcpServer (ts)

• Playwright MCP

  • Checking the connection to the browser:

    Use Playwright MCP server to find the Penpot browser tab.

---

1. One-time, if you don't already have it: set penpotFlags = "enable-mcp" in frontend/resources/public/js/config.js (gitignored; create if missing). ↩︎