artifact-editor/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

# Install in development mode
pip install -e .

# Install with all dependencies
pip install -e ".[dev]"

# Run the editor
artifact-editor

# Run from source (development)
PYTHONPATH=src python3 -m artifact_editor.cli

# Run with specific format
artifact-editor --type svg --output /tmp/test.svg

Architecture

Artifact Editor is a standalone PyQt6-based GUI for creating visual artifacts (diagrams, 3D models, code snippets) from code-based formats. It's designed to integrate with other tools via stdin/stdout and exit codes.

Project Ecosystem

This is part of a three-project stack:

1. CmdForge - AI provider abstraction and tool execution (dependency)
2. Orchestrated Discussions - Conversation orchestration (launches this editor)
3. Artifact Editor (this) - Visual artifact creation

Integration Protocol

When launched by a parent application (e.g., Orchestrated Discussions):

Parent App                          Artifact Editor
    │                                     │
    ├─ subprocess.run([                   │
    │    "artifact-editor",               │
    │    "--output", "path.puml"          │
    │  ])                                 │
    │                                     ├─ User edits/creates artifact
    │                                     ├─ User may switch format (e.g., .puml → .svg)
    │                                     ├─ User clicks Save & Exit
    │                                     │
    │  ◄────────────────────────────────  ├─ stdout: "ARTIFACT_SAVED:/actual/path.svg"
    │                                     ├─ exit code: 0 (success)
    │                                     │
    ├─ Parse stdout for ARTIFACT_SAVED    │
    ├─ Use actual path (not suggested)    │

Exit Codes:

• 0 - Success, file saved. stdout contains ARTIFACT_SAVED:/path
• 1 - User cancelled (closed without saving)
• 2 - Error (stderr contains message)

Key Design Decisions

1. Code-based formats - All artifacts are stored as text (PlantUML, Mermaid, SVG, etc.) so AI can read and modify them
2. Format switching - User can change format; output_path extension updates automatically
3. Non-destructive - Undo/redo works for both code and visual edits
4. Subprocess integration - Clean stdin/stdout contract, no shared state

Source Structure

src/artifact_editor/
├── cli.py              # Entry point, argument parsing
├── gui.py              # PyQt6 main window (~2800 lines)
├── dialogs.py          # Element editing dialogs per format
├── templates.py        # Pre-built templates (100+)
├── parser.py           # PlantUML parser
├── mermaid_parser.py   # Mermaid parser
├── openscad_parser.py  # OpenSCAD parser
├── excalidraw_parser.py # Excalidraw JSON parser
├── svg_parser.py       # SVG XML parsing
├── svg_interactive.py  # Qt-based SVG interaction
├── svg_scene.py        # QGraphicsScene SVG rendering
└── renderers/
    ├── __init__.py     # Renderer registry
    ├── plantuml.py     # Calls `plantuml` CLI
    ├── mermaid.py      # Calls `mmdc` CLI
    ├── openscad.py     # Calls `openscad` CLI
    ├── code.py         # Pygments syntax highlighting
    ├── svg.py          # Direct SVG rendering
    └── excalidraw.py   # Excalidraw JSON → SVG

Key Classes

• ArtifactEditorWindow - Main PyQt6 window with split view
• RenderThread - Background rendering to avoid UI freezes
• DictateThread - Voice input with countdown timer
• AIThread - AI generation in background
• SVGSceneManager - Interactive SVG editing with QGraphicsScene

AI Integration

Uses the artifact-ai CmdForge tool for AI-powered generation:

subprocess.run(
    ["artifact-ai", "--format", format_type, "--instruction", instruction],
    input=current_code,
    capture_output=True
)

No direct AI provider imports - follows Unix philosophy.

CmdForge Tools

Artifact Editor includes CmdForge tools for CLI/scripting use:

cmdforge/
├── artifact-ai/         # AI-powered artifact generation/modification
│   └── config.yaml      # Supports all formats: plantuml, mermaid, openscad, svg, excalidraw, code
└── artifact-export/     # Render source to binary formats (PNG, SVG, PDF)
    └── config.yaml

artifact-ai - Generate or modify artifacts using AI:

# Create new artifact
echo "" | artifact-ai --format plantuml --instruction "Create a sequence diagram for login"

# Modify existing artifact
cat diagram.puml | artifact-ai --format plantuml --instruction "Add a cache layer"

artifact-export - Render artifacts to binary formats:

cat diagram.puml | artifact-export --format plantuml --to output.svg
cat model.scad | artifact-export --format openscad --to output.png

These tools are installed to ~/.cmdforge/ and ~/.local/bin/ by ./install.sh.

Supported Formats

Format	Extension	Renderer	Visual Editing
PlantUML	.puml	plantuml CLI	Element dialogs
Mermaid	.mmd	mmdc CLI	Node/edge dialogs
OpenSCAD	.scad	openscad CLI	3D rotation, primitives
Code	.py, etc.	Pygments	Syntax highlighting
SVG	.svg	Direct	Interactive drag/resize
Excalidraw	.json	Built-in	Hand-drawn style

Toolbar Actions

• Format selector - Switch between artifact types (updates file extension)
• Save - Save to current path
• Save & Exit - Save and close (for integration workflows)
• Render button by preview - Force re-render (Ctrl+R)

AI Panel

Bottom of window:

• Text input - Natural language instructions
• Dictate - 10-second voice recording with countdown (🎤 9s, 🎤 8s...)
• AI Generate - Sends to Claude, updates code editor

External Dependencies

Required for rendering:

• plantuml - For PlantUML diagrams
• mmdc (mermaid-cli) - For Mermaid diagrams
• openscad - For 3D CAD models
• pygments - For code syntax highlighting