ascii-art

name	ascii-art
description	Generate and decode real ASCII, braille, ANSI, and 3D text art with the ditherlab CLI/MCP — from images, from geometry you describe (scene DSL), from 3D scenes and extruded text, with auto-tuned settings — apply and teach named themes, and draw by hand only with measured technique and exemplars. Use whenever the user asks for ASCII art, text art, a banner or logo for a CLI/README/MOTD, braille art, ANSI color art, dithering, a pixel/retro look, a spinning/3D terminal piece, converting an image, video, or webcam to text, an animated text GIF, identifying or decoding pasted art, or "make it look like <style>" — even if they only say "draw X in the terminal" or "make it look retro". Also use for flowcharts, sequence diagrams, state machines, timelines, mindmaps, and architecture diagrams in text (Mermaid in, box drawing out), bar/column/ spark charts from data, box-drawing tables, directory/outline trees, boxed notes, FIGlet banners, and for checking or repairing any hand-drawn text art (`ditherlab lint`). Stays active across turns once triggered. Do NOT use for box-drawing UI mockups of whole screens — draw those by hand (references/freehand.md helps), then lint them.
license	MIT

ASCII art with ditherlab

Hand-typed art fails predictably: guessed densities, ignored 1:2 cell aspect, no light direction. ditherlab dithers real pixels into characters (so the art is right by construction), renders 3D primitives, decodes art back to images, and carries themes — named looks with settings and hand-drawing rules that you can apply and extend. Use the tool for pictures; use the references for craft; save what works.

Persistence

ACTIVE EVERY RESPONSE once triggered. Still active if unsure. Off only when the user says "stop ascii-art" or "normal mode".

Setup

ditherlab --help. Not on PATH? node <clone>/bin/ditherlab.js, or clone https://github.com/daronthedragon/ditherlab (zero deps, Node 18+, npm link). MCP instead of shell: ditherlab agents mcp <client> prints the config for any MCP client (cursor, windsurf, cline, roo, vscode, zed, gemini, codex, claude — for Claude: claude mcp add ditherlab -- node <clone>/src/mcp.js); ditherlab agents install <name|all> writes these instructions where other agents read them (AGENTS.md, .cursor/rules, .github/copilot-instructions.md, …) → tools render_text_art render_3d draw_scene auto_tune banner figlet diagram table tree box lint_art gallery decode_art render_art_image dither_image list_themes save_theme info, plus resources ditherlab://references/*, ditherlab://themes, ditherlab://gallery, ditherlab://figlet-fonts. PNG, JPEG (baseline + progressive), GIF, BMP, PGM/PPM decode with zero dependencies; ffmpeg on PATH adds WebP/TIFF and video.

Procedure

Run every time, in order. Stop at the first step that resolves the task.

1. Style named or implied? ("blueprint", "Game Boy", "sketch", "for my README"): ditherlab themes. Matching theme → use --theme <name> in every command below. No match → compose settings from the references, render, and after the user approves, ditherlab theme save <name> … with a --use-when naming their phrase (references/themes.md).
2. Art from an image (photo, screenshot, logo): ditherlab inspect photo.jpg first when unsure — it reports tones, colorfulness, transparency, edge density, and the width that fits 24/40 rows, with suggested flags. Then pick mode from the table and run — or let the tool pick: ditherlab auto photo.jpg --mode braille -w 70 searches ~100 settings, scores each by how much structure survives, and prints the best art plus its command. Paste output verbatim. Add --save-theme <name> --use-when "…" when the result is worth keeping.
3. Banner text: classic FIGlet look (READMEs, CLI headers, MOTDs): ditherlab figlet "ship it" -f slant (--list shows the 15 bundled fonts — standard slant small big banner shadow script mini block lean digital bubble term smslant smscript; -f path.flf loads any FIGlet font; --width 80 --center wraps/centers). Pixel-font banner: ditherlab text "SHIP IT" (--style block|shadow|half|braille|quadrant, --frame round --title …); lowercase / a real typeface look: --font mono (8×16 glyphs; pair with --style half or braille to keep it short). Never hand-type block letters or FIGlet letters.
4. 3D / spinning / "donut" / 3D logo: ditherlab 3d torus --rx 0.9 --ry 0.6 -w 70 --mode braille; --spin --frames 24 -o spin.gif animates; --mode shape sketches; ditherlab 3d --text "GO" --ry 0.4 extrudes letters; --extrude logo.png extrudes a bitmap; --scene "sphere s=1.1; box op=subtract s=0.8 ry=0.6; torus y=-1.4 s=0.5" composes objects with CSG (op=union|subtract|intersect|smooth, x= y= z= rx= ry= rz= s=). Other forms: script pixels (PGM) then encode — the ten-line sphere in references/3d-and-shading.md.
5. "Something cool / abstract / a poster / a screensaver": ditherlab gen attractor --seed 42 -w 70 (also plant, maze --solve, truchet, plasma, automaton --rule 110, rose) — seeded, reproducible; offer two seeds. For images that must look hand-made: (strokes wrap the forms), (engraving), (dots). references/generative.md.

Picking mode and width

Destination / intent	Mode	Width
README / markdown	ascii --theme readme (braille if Unicode is fine)	≤ 80
Terminal, a human looking	ditherlab show (real pixels via kitty/iTerm2/sixel when ditherlab term says so), else symbols	terminal width
Terminal, MOTD, text required	symbols (highest fidelity: per-cell shapes + fg/bg color), braille (mono detail), symbols --mono	80–140
Chat	braille or quadrant	40–70
Plain-text only	ascii -c classic	≤ 72
Sketch / line art	shape (stroke matching) or edge; ascii --edges	60–100
Retro / pixel	quadrant, or `ansi -p gb	pico8
Shareable image of text	any mode + `-o art.svg	.html
Terminal recording / README embed	play … -o out.cast (asciinema) or -o out.gif	60–100
Subject from description	draw (2D scene) or 3d --scene/--text → any mode	50–90
Tiny icon / mascot	gallery <name> exemplar, adapted	≤ 12
Flowchart / pipeline / states	diagram (Mermaid or ), for plain text

Logos and icons: --trim drops uniform padding, --bg #fff composites transparency over the page color before rendering. Older terminals and CI logs: --colors 256 or --colors 16 re-quantizes truecolor escapes. Height budget: --rows N shrinks the width until the art fits N lines — use it whenever the destination has a known height (a 24-row terminal, a chat bubble, a README section). Tune, in order: --levels for hazy or murky photos (auto-levels), --clahe 0.4 for detail hidden in shadows/skies, --contrast 0.2 flat → punchier; --sharpen 0.6 mushy → crisp; --invert tones backwards; --paper light background; -a atkinson sparse/clean, -a bayer4 retro, -a bluenoise grain without pattern; --strength 0.5 calms a busy dither; --frame round --title when the art sits in prose; --linear (gamma-correct: mid-gray comes out ~21% ink, the true luminance, instead of 50%) when tones look too dark or too bright; --oklab for palette work (-p gb|cga|auto:N) so colors map by perceived distance. Read references/ascii-fundamentals.md before any hand adjustment; references/3d-and-shading.md for light and form.

Rules

• Never present hand-typed art as tool output. Anything beyond a 4-line doodle is produced by a ditherlab command shown in the transcript, or is explicitly labeled hand-drawn, follows references/freehand.md, and passed ditherlab lint (exit 0) before it was pasted.
• Flowcharts, tables, trees and banners come from diagram, table, tree, figlet — not from hand-aligned characters.
• Paste tool output verbatim; never retouch characters.
• Look at the result before sending, and measure it: ditherlab score art.txt image.png (or MCP score_art) returns 0..1 structure preserved — below 0.75 means rerun with auto, a wider width, or symbols/braille. This works for hand-drawn art against a reference image too.
• ANSI escapes go only to terminals; files and markdown get ascii, braille, blocks, or an exported .svg/.html/.png.
• Respect the width column; wider than the medium wraps into noise.
• A look the user approves gets saved as a theme before the turn ends.
• When settings are in doubt, run auto before fiddling by hand; when the subject is in doubt, describe geometry (draw, 3d --scene) before typing characters.
• Exact-font output: if the destination font matters, export a glyph atlas from the web UI (download ▾ → glyph atlas) and ditherlab font <file>; shape and render then match that font's real glyphs.

Example

Instead of:

Here's a sphere for your README:
      ___
    /     \
   |  ( )  |
    \ ___ /

Do:

$ ditherlab 3d sphere -w 46 --theme readme
[paste of the actual command output]

References (read when relevant, not all at once)

• references/ascii-fundamentals.md — cell aspect, measured glyph density, stroke vocabulary, Unicode families, medium limits, composition.
• references/3d-and-shading.md — ditherlab 3d, the PGM compute-first method, isometric/perspective rules, shading order, materials, animation.
• references/freehand.md — grid passes, block letters, frames, tiny icons, diagrams, failure table.
• references/themes.md — schema, resolution order, theme save, config defaults, style-by-name workflow.
• references/terminal-graphics.md — term/show: kitty, iTerm2, sixel protocols, when pixels beat characters, reading CP437 ANSI art.
• references/generative.md — flow/hatch/stipple modes, gen kinds, seeds, recipes for posters and textures.
• references/motion.md — fx: cameras, reveals, particle layers, CRT, keyframe paths, duration taste per medium, the Director tab.
• references/diagrams.md — diagram: the Mermaid subset and a -> b syntax, styles, directions, how layout and routing work, what to do when a chart is too wide; table, tree, box, figlet, lint.
• gallery.json (ditherlab gallery) — 30 exemplars with proportion/stroke notes: animals, objects, symbols, UI sets, shaded sphere, isometric cube.
• scenes: ditherlab draw --example … — five worked scene files to copy.

Observable effect

Every piece of art in a reply is preceded by the ditherlab command (or MCP call) that produced it — auto when settings were uncertain, draw/3d when the subject had no image, diagram/table/tree/figlet for structured text — or is labeled hand-drawn with the gallery piece / theme / reference it followed and a lint result; doubtful results show a score; pasted art gets a decode; a liked look ends in theme save. The eval counts exactly this.