Omnigraffle

OmniGraffle

Written by the repository maintainer, 2026. Public — MIT License (see LICENSE.txt).

Work with OmniGraffle documents (.graffle, .gtemplate, .gstencil) safely and correctly: inspect them, convert other formats into them, edit or repair them, and export them back out. OmniGraffle files are not plain text and not one fixed binary shape — the same .graffle extension can hide a zip archive, a Finder-style package directory, a gzip-compressed plist, a raw XML plist, or a binary plist. Treat every document as unknown until detected, and prefer OmniGraffle itself to write, import, render, and validate the result rather than hand-editing serialized data.

Before doing anything: restate scope

State the source path and the requested output path (or, for pure inspection, just the source path). Classify the request into one of: inspect, modify, create, import (into OmniGraffle), export (out of OmniGraffle), repair, or validate. This classification decides which section below applies and what "done" means.

Non-negotiable safety rules

1. Never overwrite the source file. Always write to a new output path or a timestamped backup before touching anything. If the user gave an output path, use it; if they didn't and this is a modification of an existing document, create <name>_<YYYYMMDD-HHMMSS>.graffle next to the original rather than replacing it, and say so.
2. Never upload a customer or user document to any online converter or web service. All conversion happens locally through OmniGraffle itself, plutil, plistlib, or the bundled scripts.
3. Never treat a binary .graffle as ordinary text. Don't cat, sed, or grep -text a raw document. Detect its variant first (scripts/grafflectl detect) and use the matching reader.
4. Never do a blind search-and-replace inside data.plist. Plists are typed, nested structures; a text-level replace can corrupt a value's type, truncate binary data, or land inside the wrong key entirely. Load it structurally (plistlib, or plutil -convert) before changing anything.
5. Never regenerate a whole document from a simplified JSON summary. A JSON inventory built for Claude to read is deliberately lossy (see references/file-formats.md). Writing a document back from that summary silently drops unknown keys, embedded assets, styles, and metadata. Only the typed-JSON round trip described in references/file-formats.md is safe to write back from, and even then only as a controlled fallback (see Rule 7).
6. Preserve everything not explicitly being changed — unknown plist keys, binary values, embedded assets, styles, layers, IDs, and relationships. When in doubt, copy the input forward unchanged rather than reconstructing it.
7. Prefer OmniGraffle itself as the writer, importer, renderer, and validator. Direct plist patching (references/file-formats.md, references/validation.md) is a controlled fallback for the narrow case where native automation genuinely cannot expose the needed property — not a default path.
8. Work in a temporary directory for extraction and intermediate files (mktemp -d). Don't leave scratch files next to the user's documents.
9. Do not claim a creation, edit, or conversion is complete until the output has been saved, closed, and reopened in OmniGraffle without error, per references/validation.md. Inspection-only tasks don't require this (OmniGraffle doesn't need to be running to read a file), but anything that writes a document does.
10. If OmniGraffle is unavailable, or its installed license can't write the required format, report the blocker plainly rather than silently falling back to something weaker. Say what's missing and what would unblock it.

Step 1: Environment discovery

Run this once per session (skip if already done this session):

scripts/grafflectl doctor

This confirms: macOS, OmniGraffle's install path/version/build/bundle identifier, whether its scripting dictionary exposes the operations this skill needs, Python 3 + plistlib, the standard CLI tools (file, unzip, gzip, ditto, plutil, osascript, sdef, open), and temp-directory write access. Read references/automation.md for what the doctor output means and how to react to a missing capability (e.g. OmniGraffle not found, or an older version whose dictionary lacks an operation this task needs).

Locate OmniGraffle by bundle identifier, not by a hardcoded application name — a user may have OmniGraffle 6, 7, or a renamed/relocated copy. scripts/omnigraffle_bridge.applescript application-info does this and records path, version, build, bundle ID, and (via sdef) which scripting commands are actually available. Never call an AppleScript or Omni Automation command that sdef didn't confirm exists.

Step 2: Detect and inspect the input

For any existing .graffle/.gtemplate/.gstencil, or any SVG/PDF/Visio file being converted in:

scripts/grafflectl detect "<input>"
scripts/grafflectl inspect "<input>"

detect identifies which of the five OmniGraffle variants (or which foreign format) this file is, using magic bytes and file/unzip -l/plutil — never by guessing from the extension. inspect prints a short structural summary (canvas count, layer count, top-level graphic counts, embedded asset count, document/app version) without dumping the full plist into context. Full detail lives in references/file-formats.md.

Do not put the raw plist or the raw SVG source into your own context as a first move. Build a concise inventory instead:

scripts/grafflectl inventory "<input>" /tmp/<workdir>/inventory.json

Then read the resulting JSON (it's small) rather than the source document. The inventory covers document/application versions; canvas names, IDs, sizes, order; layer names, order, visibility, locking, printability; the graphic hierarchy, classes, names, and user data; text; bounds and rotation; shape types; groups and nested groups; lines and endpoints; connections and magnets; fill, stroke, font, and text properties; image references; embedded asset filenames; notes/metadata; and cross-references. See references/file-formats.md for what each of these looks like inside the plist and how the script builds them defensively (OmniGraffle's plist schema varies slightly by document and app version — the script introspects rather than assuming a fixed shape, and so should any manual follow-up).

Step 3: Choose the method — native automation first

Read references/automation.md before calling the bridge: it explains how the bridge determines which AppleScript verbs and which Omni Automation JavaScript entry points are actually available for the installed version, and how to fall back correctly when one path isn't exposed. Never hard-code an application name, file-type identifier, or scripting command the installed dictionary hasn't confirmed.

Step 4: Do the work

• SVG → OmniGraffle: follow references/conversion-workflows.md in full — it covers SVG inventory (viewBox, paths, groups, text, fonts, transforms, gradients, clipping, masks, markers, embedded/external images), resource resolution, the native import call, whether the result stayed vector-editable or got flattened into one object, and the visual diff pass against the source.
• Export: use scripts/omnigraffle_bridge.applescript export-pdf|export-png|export-svg. Confirm canvas count and dimensions match expectations before declaring the export done.
• Direct plist patching (fallback only): follow the procedure in references/file-formats.md ("Direct plist patching") exactly — extract to a temp workspace, parse with plistlib, apply a narrow deterministic change, preserve every untouched key and asset, re-serialize, rebuild any zip archive with files at the archive root (no extra enclosing directory), then hand the provisional result back to OmniGraffle for open → save → close → reopen → render before trusting it.

Step 5: Validate

Every task that produced or changed a document goes through references/validation.md's checklist before you report success: structural validity (archive integrity, data.plist parses, every referenced asset exists), OmniGraffle opens it without error, saves it, closes it, reopens the saved copy, and every relevant canvas renders. For conversions specifically, check for missing graphics, displaced objects, changed colors, broken gradients, wrong transparency or clipping, font substitution, altered text, wrong line endings, and unexpected flattening — and fix confirmed differences, then re-run the save/close/reopen/render cycle.

If something in this checklist can't be completed (OmniGraffle isn't installed, a needed operation isn't in the scripting dictionary, a feature genuinely doesn't survive import), that is a reported limitation, not a silent gap.

Step 6: Report

Close with a completion report — see references/validation.md for the exact fields (source path, output path, backup path, OmniGraffle version used, writing/import method, whether objects stayed editable, canvas/layer/graphic/asset counts, structural validation result, reopen test result, render validation result, confirmed limitations). Don't claim something was copied, matched, converted, or validated unless it actually happened in this session.

Reference map

Scripts

grafflectl shells out to both of the above — call grafflectl for everyday use, and drop to the underlying scripts directly only when a task needs an operation grafflectl doesn't wrap yet.