Getting Started

artwright is four skill folders and one Python script. An agent loads the skills from their descriptions and runs the script itself; you rarely type aw.py by hand, but you can, and every page of this wiki shows it that way.

What you need

Need	Detail
An agent that reads skills	Claude Code as a plugin; GitHub Copilot, Cursor and Codex by copying the skill folders (the README names these four; only Claude Code was run for this wiki)
Python 3.9 or later	aw.py uses the standard library only. CI runs it on Linux, macOS and Windows with Python 3.9 and 3.14
Pillow (optional)	Version 11 or later. Faster, and it decodes every common format. Without it, PNG is decoded in pure Python
ffmpeg (optional)	Used only when Pillow is absent, to decode JPEG, WebP and other formats

aw.py makes no network request unless you name a Lospec palette that is not cached yet, or run doctor --probe (see Commands).

Install in Claude Code

Add the repository as a plugin marketplace, then install the plugin from it. In Claude Code, type these two commands.

/plugin marketplace add m4bwav/artwright
/plugin install artwright@artwright

These two commands were not run for this wiki. What was run: loading the plugin from a clone of the v0.7.1 tag with --plugin-dir, which also works for trying it without installing anything.

git clone https://github.com/m4bwav/artwright
claude --plugin-dir ./artwright plugin details artwright

The inventory part of what Claude Code 2.1.281 printed for 0.7.1:

Component inventory
  Skills (4)  artwright, artwright-curate, artwright-judge, artwright-pixel
  Agents (0)
  Hooks (0)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~933 tok   added to every session

Per-component (rounded)
  component         always-on  on-invoke
  artwright              ~230      ~3.4k
  artwright-curate       ~210      ~1.6k
  artwright-judge        ~250      ~2.9k
  artwright-pixel        ~250      ~2.2k

The always-on cost is the four skill descriptions; the rest loads only when a skill fires.

Install in other agents

Link or copy each folder under skills/ into your agent's skills folder: ~/.claude/skills, ~/.agents/skills, ~/.copilot/skills or .cursor/skills. The folders come from a clone or from artwright-0.7.2.zip on the release page, which holds the same aw.py, aw_measure.py and aw_geom.py these pages were checked with (same SHA-256). Install all four together. The three sibling skills run the hub's script by the relative path ../artwright/scripts/aw.py, so they need the artwright folder beside them. This route was not run for this wiki.

Optional, for speed and every image format:

pip install pillow

Where aw.py is

The script is skills/artwright/scripts/aw.py inside the plugin. The skills tell the agent to run it by its full path from your folder, so the files it writes land in your folder, not the plugin's. On this wiki, python aw.py stands for python <the plugin>/skills/artwright/scripts/aw.py.

Since 0.2.0 the light, colour and composition measures live in a second file, aw_measure.py, and since 0.4.0 the render, sprite and series gates (geomgate, sprite, setfit) live in a third, aw_geom.py. aw.py imports both from its own folder. Keep the three together: an aw.py copied on its own fails on every command, even --version, with ModuleNotFoundError: No module named 'aw_measure' on stderr.

Check what works on your machine

python aw.py doctor

With Pillow installed, on Linux, this prints:

{
 "artwright": "0.7.2",
 "python": "3.14.4",
 "python_ok": true,
 "pillow": "13.0.0",
 "ffmpeg": false,
 "home": "/home/you/.artwright",
 "home_exists": false,
 "decode": [
  "pillow"
 ],
 "notes": [],
 "ok": true
}

Without Pillow and without ffmpeg, decode shrinks to PNG and a note says how to get the rest:

{
 "artwright": "0.7.2",
 "python": "3.14.4",
 "python_ok": true,
 "pillow": null,
 "ffmpeg": false,
 "home": "/home/you/.artwright",
 "home_exists": false,
 "decode": [
  "png (stdlib)"
 ],
 "notes": [
  "PNG only: install Pillow (pip install pillow) or ffmpeg to read JPEG and WebP"
 ],
 "ok": true
}

On Windows with Python 3.9, no Pillow and ffmpeg on the PATH, decode read ["png (stdlib)", "jpeg, webp and more (ffmpeg)"] with no notes.

home is where the private taste record lives: ARTWRIGHT_HOME when set, otherwise .artwright in your home folder. home_exists stays false until something is written there: a cache put, a cache label or a fetched palette.

First commands

Look before reading: info gives the size and the token cost (see Home for its output). A large image is fitted before the agent reads it, to a long edge of 1024 by default:

python aw.py fit dusk.png -o dusk_1024.png

prints:

{
 "out": "dusk_1024.png",
 "size": [
  1024,
  614
 ],
 "tokens": {
  "standard": {
   "tokens": 814,
   "read_at": [
    1024,
    614
   ]
  },
  "high": {
   "tokens": 814,
   "read_at": [
    1024,
    614
   ]
  }
 },
 "ok": true
}

Several images go on one contact sheet, read once, rather than one read each. Cells are labelled A, B, C and the map says which file is which:

python aw.py sheet renders -o sheet.png

prints:

{
 "out": "sheet.png",
 "size": [
  1176,
  786
 ],
 "cell": 384,
 "map": {
  "A": {
   "file": "renders/render_01.png"
  },
  "B": {
   "file": "renders/render_02.png"
  },
  "C": {
   "file": "renders/render_03.png"
  },
  "D": {
   "file": "renders/render_04.png"
  },
  "E": {
   "file": "renders/render_05.png"
  },
  "F": {
   "file": "renders/render_06.png"
  }
 },
 "tokens": {
  "standard": {
   "tokens": 1218,
   "read_at": [
    1176,
    786
   ]
  },
  "high": {
   "tokens": 1218,
   "read_at": [
    1176,
    786
   ]
  }
 },
 "ok": true
}

Next: Commands for everything else, or Recipes for whole tasks.