Vectis CLI

Vectis is a slash-command REPL that connects to a self-hosted Penpot instance via its official MCP server and uses the Claude API for AI-powered design generation, auditing, and analysis, all from your terminal.

The CLI is the brain. Each project folder is its memory. Penpot is the canvas. Slash commands are the language. @references are the inputs.

Features

Installation

Prerequisites

Setup

# Clone and install
git clone https://github.com/dinethlive/vectis-cli.git
cd vectis-cli
bun install

# Start in dev mode
bun run dev

# Run the setup wizard (configures API key, Penpot URLs)
# Inside the REPL:
/init

Penpot + MCP Server

Vectis expects a Penpot instance and its MCP server running locally. Everything you need is in docs/penpot-setup/:

cd docs/penpot-setup
bash start-penpot.sh       # Start Penpot (Docker) → http://localhost:9001
bash setup-mcp.sh          # First time: clone Penpot repo + install MCP deps
bash start-mcp.sh          # Start MCP server → ports 4400/4401/4402

See the full setup guide for plugin connection, troubleshooting, and more.

Quick Start

bun run dev

  ╭────────────────────────────────────────────────────╮
  │░░░░░░░░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓██████████████│
  │                                                    │
  │   ██╗   ██╗███████╗ ██████╗████████╗██╗███████╗   │
  │   ██║   ██║██╔════╝██╔════╝╚══██╔══╝██║██╔════╝   │
  │   ██║   ██║█████╗  ██║        ██║   ██║███████╗   │
  │   ╚██╗ ██╔╝██╔══╝  ██║        ██║   ██║╚════██║   │
  │    ╚████╔╝ ███████╗╚██████╗   ██║   ██║███████║   │
  │     ╚═══╝  ╚══════╝ ╚═════╝   ╚═╝   ╚═╝╚══════╝   │
  │                                                    │
  │  AI-driven design engineering for Penpot           │
  │  v0.1.0  ·  Type /help for commands               │
  │                                                    │
  ╰────────────────────────────────────────────────────╯

vectis >

# Check everything is connected
/doctor

# Scan your Penpot file
/pull

# Generate a UI board from a description
/create Login "A clean login form with email, password, and a sign-in button"

# Ask Claude about your project with context
/ask "what tokens do we use?" @context/tokens.json

# Audit an existing board against design rules
/audit Dashboard/Home

Commands

Setup & Health

AI & Design Generation

Project Navigation

Skills & Tokens

Session & History

Misc

The /create Pipeline

The core design generation flow:

Description ──► Prompt Assembly ──► Claude (tool_use) ──► Post-Process ──► Validate ──► Preview ──► Penpot
                     │                    │                    │              │           │           │
              system prompt +      LayoutSpec JSON      4px grid snap    Zod schema   ASCII tree   Plugin JS
              skills + tokens +    via structured       min 32px touch   + business   renders      (flex/grid)
              component patterns   output tool          fill text defaults  rules      the spec

1. Prompt Assembly - System prompt with LayoutSpec schema, design principles, component pattern library (11 patterns), active skills, and detected layout template
2. Generation - Claude returns a structured LayoutSpec via tool_use for reliable JSON extraction
3. Post-Processing - Snap to 4px grid, enforce 32px minimum for interactive elements, fill text defaults, warn on low contrast
4. Validation - Zod structural validation + business rules (token refs, naming conventions, layout requirements)
5. Preview - ASCII tree preview in the terminal
6. Push - User chooses: push to Penpot, edit, regenerate, save spec, or quit

@reference System

Pull external context into any AI command:

# Local files
/ask "explain this" @src/components/Button.tsx

# Entire folders
/ask "summarize the brief" @briefs/

# Penpot boards
/ask "what's wrong with this layout?" @penpot:Dashboard/Home

# Penpot shortcuts
@penpot:selection          # Currently selected shapes
@penpot:tokens             # Design tokens
@penpot:components         # Component library
@penpot:page/Dashboard     # All boards on a page

# Images
/ask "recreate this" @image:mockup.png

Configuration

Precedence

Environment variables  >  Project config  >  Global config  >  Defaults

Config Files

~/.vectis/config.json          # Global (API key, default model)
<project>/.vectis/config.json  # Project (Penpot file, MCP URLs, model override)

Global Config

{
  "anthropicApiKey": "sk-ant-...",
  "defaultModel": "claude-sonnet-4-20250514",
  "globalSkillsDir": "~/.vectis/skills"
}

Project Config

{
  "penpotFileId": "...",
  "penpotFileUrl": "http://localhost:9001/...",
  "mcpServerUrl": "http://localhost:4401/mcp",
  "wsServerUrl": "ws://localhost:4402",
  "model": "claude-sonnet-4-20250514"
}

Environment Variables

Project Structure

src/
  index.ts              # Entry point
  constants.ts          # Version, defaults, limits
  types/                # VectisError, Config, ReplState, SessionContext
  config/               # Layered config loading + Zod schemas
  ai/                   # Claude client (streaming + tool_use), retry, RAG, prompts
  bridge/               # Penpot MCP client + WebSocket listener
  references/           # @file, @folder, @penpot, @image resolver + security
  workspace/            # Context assembler (system prompt + refs + skills)
  graph/                # SQLite graph store, migrations, CRUD
  conversation/         # Store, compactor, history
  generation/           # Spec pipeline: generator → postprocess → validator → renderer
  structure/            # /structure analyser, conversation, writer, differ
  skills/               # Registry, loader, installer
  context/              # Event processor, pending queue
  utils/                # Logger, spinner, platform, JSON output
  repl/
    theme.ts            # Truecolor purple palette (6 shades)
    banner.ts           # ANSI-shadow gradient banner
    prompt.ts           # Mode/flow/stream indicators
    session.ts          # REPL loop, readline, slash dispatch
    commands/           # 30+ slash command handlers
    ...                 # vim-mode, paste-mode, completer, keybindings, signals

Tech Stack

Development

# Start dev REPL
bun run dev

# Run tests
bun test

# Type check
bun run lint

# Build for distribution
bun run build

Workspace Layout

When you run /init and /structure, Vectis creates this in your project:

your-project/
├── briefs/                  # Your messy input files
├── .vectis/
│   ├── config.json          # Project config
│   ├── graph.db             # SQLite graph store
│   ├── skills/              # Project-local skills
│   └── conversations/       # Session history
├── context/
│   ├── project.md           # Generated by /structure
│   ├── flows/               # Flow definitions
│   ├── screens/             # Screen definitions
│   └── tokens.json          # Design tokens
├── specs/                   # Saved LayoutSpec files
└── exports/                 # CSS/Tailwind token exports

License

MIT

Status & Contributing

Vectis is under active development. Expect breaking changes as the core stabilises, but things will improve steadily with each release.

Why this exists: Context loss is the single biggest problem in AI-assisted design today. AI can generate beautiful UIs, but without project context (tokens, flows, screens, constraints) the output is disconnected from reality. Vectis exists to fix that: a CLI that manages and preserves design context, with Penpot as the canvas.

Contributions are welcome. Open an issue for bugs or ideas, or submit a pull request. All feedback helps.