Installation

Pencil is available as an IDE extension and a standalone desktop application. Choose the option that best fits your workflow.

VS Code Extension

Installation

Open VS Code
Go to Extensions (Cmd/Ctrl + Shift + X)
Search for “Pencil”
Click Install

Verification

Create a new file with a .pen extension (e.g., test.pen)
Open the file
Look for the Pencil icon in the top-right corner of the editor

If you don’t see the icon:

Open Command Palette (Cmd/Ctrl + Shift + P)
Search for “Pencil” to see available commands
Check that the extension is enabled in your Extensions panel

Cursor Extension

Installation

Open Cursor
Go to Extensions
Search for “Pencil”
Click Install

Verification

Same as VS Code - create a .pen file and verify the Pencil icon appears.

Common Issues

Extension doesn’t connect:

Ensure Claude Code is logged in (claude CLI)
Complete the activation process
Check that Pencil MCP server is connected

Don’t see the prompt editor/prompt box:

Check activation/login status
Restart Cursor
Reinstall the extension if issues persist

“You need Cursor Pro” message:

This may occur depending on Cursor’s plan/tooling restrictions
Check your Cursor subscription status

Desktop Application

macOS

Download:

Get the latest .dmg from the Pencil website or releases page
Drag Pencil to your Applications folder
Launch Pencil

First Launch:

macOS may ask you to verify the app (right-click → Open if you see a security warning)
Complete the activation process
Login to Claude Code if you plan to use AI features

Linux

Supported:

Pencil runs on Linux
Download the appropriate package for your distribution

Known Issues:

Some Wayland/Hyprland UI issues may occur
X11 environments are more stable

Installation:


# Example for .deb package
sudo dpkg -i pencil-*.deb
 
# Example for .AppImage
chmod +x pencil-*.AppImage
./pencil-*.AppImage

Windows

Desktop App:

Not currently available for Windows
Windows users should use the VS Code or Cursor extension

Extension (Windows):

Follow the VS Code or Cursor installation instructions above
Works the same as on macOS/Linux

Claude Code CLI

Pencil’s AI features require Claude Code to be installed and authenticated.

Installation


# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code-cli
 
# Or using the official installer
curl https://claude.ai/cli/install.sh | sh

Authentication


# Login to Claude Code
claude
 
# Follow the browser authentication flow

Verification


# Check that you're logged in
claude --version

MCP Server

The Pencil MCP (Model Context Protocol) server runs automatically when you use Pencil. It provides AI assistants with tools to read and manipulate .pen files.

Automatic Setup

The MCP server starts when you open Pencil
It runs locally on your machine
No additional configuration needed for basic use

Verification

In Cursor:

Open Settings → Tools & MCP
Verify Pencil appears in the MCP server list

In Codex CLI:

Run Pencil first
Open Codex
Run /mcp
Pencil should appear in the MCP list

Post-Installation

After installing Pencil:

Complete activation - You’ll need to activate Pencil with your email
Login to Claude Code - Required for AI features
Open the welcome file - Right-click canvas → Open Welcome File
Create your first design - See Getting Started

Updating Pencil

VS Code/Cursor Extension

Extensions update automatically by default. To manually update:

Go to Extensions
Find Pencil
Click Update if available

Desktop App

The app will notify you when updates are available
Download and install the latest version from the website

Troubleshooting Installation

Extension installed but doesn’t connect:

Verify Claude Code is logged in
Complete the activation process
Restart your IDE

Activation email not received:

Check spam/junk folder
Try a different email address
Reinstall the extension

“Invalid API key” or “Please run /login”:

Run claude CLI and complete authentication
Ensure no conflicting auth configurations (environment keys, custom providers)

See the full Troubleshooting guide for more issues and solutions.