mise-en-scene

CLI bootstrap for mise en scene. One command to install and configure the full design toolkit — detects your agent environment (Claude Code, Cursor, or both), registers MCP servers, installs hooks, deploys the skill file + references to .agents/skills/, and scaffolds the project directory.

All dependencies (@mise-en-scene/server, @mise-en-scene/taste-memory) are bundled — no separate installs needed.

Quick Start

npx mise-en-scene init

This single command:

1. Detects Claude Code (~/.claude/) and Cursor (~/.cursor/)
2. Registers both MCP servers in each platform's config (scoped correctly per platform)
3. Installs hooks into .claude/ and .cursor/ (post-design SVGO optimization, post-export file opener, session-start server launcher)
4. Deploys SKILL.md + references to .agents/skills/mise-en-scene/ (platform-agnostic)
5. Scaffolds mise-en-scene/ in your project

Commands

init

mise-en-scene init [--dir <path>]

Full bootstrap. Safe to run multiple times — merges configs without duplicating entries, preserves existing files.

serve

mise-en-scene serve [--port 3333] [--dir mise-en-scene/main]

Start the design preview server. Serves HTML designs with hot-reload and WebSocket feedback.

stop

mise-en-scene stop [--port 3333]

Stop the design server and shut down Puppeteer.

export

mise-en-scene export [--format png] [--output path] [--width 1080] [-H 1080] [--quality 90]

Export the current design. Requires the server to be running.

| Flag | Default | Description | |------|---------|-------------| | -f, --format | png | Format: svg, png, jpg, pdf | | -o, --output | mise-en-scene/exports/design.<fmt> | Output path | | -w, --width | — | Width in pixels | | -H, --height | — | Height in pixels (uppercase to avoid -h conflict with help) | | -q, --quality | 90 | JPEG quality (1-100) |

gallery

mise-en-scene gallery

Open the version gallery in your default browser. Shows all branches and versions as thumbnail cards.

taste

mise-en-scene taste [--scope merged] [--project <name>]

Print a summary of the current taste profile from the taste memory database.

clean

mise-en-scene clean [--dir <path>] [--all]

Reset project state. Clears branches and main versions, removes feedback and gallery cache. Keeps exports/ unless --all is passed.

Platform Detection

The CLI checks for these directories in $HOME:

| Directory | Platform | Detected | |-----------|----------|----------| | ~/.claude/ | Claude Code | Yes → configures hooks + MCP | | ~/.cursor/ | Cursor | Yes → configures hooks + MCP |

Both platforms are configured when both are detected. Skills always go to .agents/skills/ regardless of which platforms are present.

What Goes Where

Skills (platform-agnostic)

Skills are installed to .agents/skills/mise-en-scene/ — shared across all agent platforms:

.agents/skills/mise-en-scene/
├── SKILL.md                     # Creative methodology for AI agents
└── references/
    ├── manifesto.md             # Design philosophy
    ├── typography-guide.md      # Font selection + pairing principles
    └── font-pairings.json       # Curated font taxonomy

MCP Config (per platform, scoped)

| Scope | Claude Code | Cursor | |-------|-------------|--------| | Project | .mcp.json (project root) | .cursor/mcp.json | | Global | ~/.claude.json | ~/.cursor/mcp.json |

Both configs contain the same servers:

{
  "mcpServers": {
    "mise-en-scene-server": {
      "command": "npx",
      "args": ["@mise-en-scene/server"]
    },
    "mise-en-scene-taste-memory": {
      "command": "npx",
      "args": ["@mise-en-scene/taste-memory"]
    }
  }
}

Existing servers in the config are preserved.

Hooks (per platform)

Hooks must live in each platform's own directory:

| Platform | Config file | Scripts directory | |----------|------------|-------------------| | Claude Code | .claude/settings.json (PascalCase events) | .claude/hooks/mise-en-scene/ | | Cursor | .cursor/hooks.json (camelCase events) | .cursor/hooks/mise-en-scene/ |

Three shell scripts are installed:

| Hook | Trigger | Action | |------|---------|--------| | post-design.sh | After studio_preview | Runs SVGO optimization on the design file | | post-export.sh | After studio_export | Opens the exported file in the system viewer | | session-start.sh | Session start | Starts the design server if not already running |

All hooks read input from stdin and fail gracefully.

Project Scaffold

init creates this structure in your project:

mise-en-scene/
├── references/     # Drop reference images here
│   └── .gitkeep
├── exports/        # Exported designs land here
│   └── .gitkeep
├── main/           # Main design branch (versioned HTML)
│   └── .gitkeep
└── branches/       # Design branches
    └── .gitkeep

Programmatic Usage

import { resolveSkillPaths, detectPlatforms } from 'mise-en-scene/detect-platform';
import { writeMcpConfig } from 'mise-en-scene/config-writer';
import { installHooks } from 'mise-en-scene/hooks-installer';
import { scaffoldProject } from 'mise-en-scene/scaffold';

const homeDir = os.homedir();
const projectDir = process.cwd();

// Skills — platform-agnostic
const skill = resolveSkillPaths(homeDir, projectDir, 'project');
// skill.skillDir → <projectDir>/.agents/skills/mise-en-scene/

// Hooks + MCP — per detected platform
const platforms = detectPlatforms(homeDir, projectDir, 'project');
for (const platform of platforms) {
  writeMcpConfig(platform.mcpConfig);
  installHooks({
    platform: platform.name,
    hooksDir: platform.hooksDir,
    hooksConfigPath: platform.hooksConfigPath,
  });
}

// Scaffold project
scaffoldProject(projectDir);

Development

npm test                # Run tests (21 unit + 4 integration)
npm run build           # Compile TypeScript
npm run test:watch      # Watch mode