ASCII art with AI coding agents

Tell Claude, Cursor or any AI coding agent to add an animated ASCII piece to your project. Copy-paste instructions included.

Loading the builder…

/WHY

Coding agents like Claude Code, Cursor and Copilot can add a piece to your project from one sentence, as long as they know how the library works. Without that, they guess slugs, forget the closing tag or load the script on the server.

The builder writes a precise prompt for the change you want and a rules file for your agent (CLAUDE.md, a Cursor rule, Copilot instructions, .windsurfrules or AGENTS.md) so every future request gets it right first time.

/EXAMPLES

Ready-made examples to copy

Each one is complete. Copy it as it is, or change the piece name to any piece in the library.

One-line requests that work

With the rules file in place, short requests are enough.

Add the great-wall-sunset piece as the hero on the home page, halftone dots look.
Replace the spinner in components/Loading.tsx with the progress-loader piece.
Make app/not-found.tsx with the page-404 piece and a link home.
Add an animated header to README.md using spinning-torus, dark and light GIFs.

Point it at the piece list

The JSON index lists every slug, name, category and tag, so the agent can choose for you.

Read https://www.ascii-magic.com/ascii/index.json and pick a calm night-sky piece for the footer of the about page. Tell me which one you chose and why.

How to do it

Browse the library and note the slug of the piece you want.
Paste the prompt below into your agent, with your slug.
Review the change it makes before you commit.

/GUIDE

What the rules file teaches

The script tag goes once per page, the element always has a closing tag, slugs must come from the index, frameworks with server rendering load the script only in the browser, and READMEs use exported GIFs or SVGs. Those five points cover nearly every mistake an agent makes.

Review the change

Agents are fast but not careful about duplicates. After the change, check that the script tag was not added to every component, and that real text, not the art, carries the page's heading.

Pieces that work well for this

Open any of them to copy the code or export.

Amsterdam Canal BicyclesCities of the World

Analog Wall ClockThings

Apollonian GasketAlgorithms

Asteroid BeltCosmos

Aurora CurtainsDemoscene

Autumn Road CyclistLandscapes

Bar Chart RaceLive Data

Home Computer BASICRetro Computing

/FAQS

ASCII art with AI coding agents: frequently asked questions

Q. How do I get an AI coding agent to add ASCII art to my project?

Paste the builder's prompt into your agent's chat: it names the task, your stack and the piece slug, and points the agent at the piece index and the rules. Save the rules file in your repository too, so every later request gets the ASCII art right the first time.

Q. Which AI coding agents does the rules file work with?

The builder writes rules files for Claude Code, Cursor, Copilot and Windsurf, plus an AGENTS.md file that many other agents read. The rules are the same in each; only the file name and, for Cursor, a short header change. Pick Other for any agent not listed.

Q. Where do I put the rules file for my agent?

In your repository: append it to CLAUDE.md for Claude Code, save it as .cursor/rulesASCII library.mdc for Cursor, use .github/copilot-instructions.md for Copilot, .windsurfrules for Windsurf, or AGENTS.md for other agents. The agent reads it on every request, so you only set it up once.

Q. What does the ASCII rules file teach an agent?

It teaches the five rules that prevent most agent mistakes. Load the script once per page, always close the ascii-art tag, take slugs from the index instead of inventing them, load the script only in the browser for server-rendered frameworks, and use exported GIFs or SVGs in READMEs. It also lists every attribute and the terminal command.

Q. How does an agent find the right piece for my project?

It reads the JSON index at ascii-magic.com/ascii/index.json, which lists every piece with its slug, name, category, tags and size in columns and rows. You can name a slug yourself, or describe what you want, such as a calm night-sky piece for the footer, and let the agent choose and explain.

Q. What can I ask an AI agent to build with ASCII art?

You can ask it to add a hero, a loader, a 404 page, a README header or a CLI splash. The builder has a ready prompt for each: a hero next to the main heading, a replacement for your loading spinner, a 404 page with a link home, dark and light README headers, and a splash that only plays in a terminal. Your stack, such as Next.js App Router, goes into the prompt too.

Q. What should I check after the agent adds the art?

Check five things, which the builder's review tab lists. The script tag appears once, not in every component; the ascii-art element has a closing tag; in server-rendered frameworks the script loads only in the browser; the slug exists in the index; and real text, not the art, carries the page's heading.

Q. Why does the page show a no piece message instead of the animation?

The element could not find that slug, so it prints a short ascii-art: no piece message in its place. Agents sometimes invent a plausible name. Look the slug up in the index or on the piece's own page, fix the piece attribute, and the animation appears.

Q. How does an agent add ASCII art in Next.js without breaking server rendering?

It should load the script with next/script or inside a useEffect, so it only runs in the browser, and put a ts-expect-error comment above the ascii-art element in TSX files. The rules file spells this out, and the generated prompt reminds the agent to use client-only loading.

Q. Can an AI agent write a brand new ASCII piece?

Yes. Ask it to read the library README, which explains the piece format: a small JavaScript module that exports its meta and a create function returning a draw function from time to a frame of text. The README also describes the validator, which checks frame size, characters, motion and drawing speed.

Q. Can an agent play a piece in my terminal to preview it?

Yes. The rules file includes the terminal command, so an agent can run npx --yes https://www.ascii-magic.com/ascii/cli.tgz with a slug to play it, add --frame to print one still frame, or --look=dots to try a different look. That is a quick way to compare pieces before wiring one into the page.

Q. Do short one-line requests work once the rules file is installed?

Yes. With the rules in place, a sentence such as add the progress-loader piece as the spinner in my loading component is enough, because the agent already knows the script, the tag and where to find slugs. Still review the change before you commit it.

Other ways to use it

Each one has its own builder.

ASCII art GIFs for newsletters and email

Export animated ASCII art as a GIF for newsletters and email, where scripts and video do not play.

README

Animated ASCII art for a GitHub README

Put an animated ASCII banner, scene or loader at the top of your GitHub README. Copy a GIF or SVG, no build step, works in GitHub's dark and light themes.

Website

An animated ASCII hero for GitHub Pages

Add a live, animated ASCII art hero to a GitHub Pages or personal website with one script tag. No framework, no build step, under 10 KB per piece.

Terminal

A terminal welcome screen with animated ASCII art

Show an animated ASCII piece every time you open a terminal, or set a still one as your server's message of the day. Works with zsh, bash and fish.

CLI

Splash screens and loaders for command line tools

Give your CLI a startup splash or an animated loader in ASCII. Copy the piece source into your Node project, or print frames from any language.

Loader

ASCII loading spinners and progress bars for websites

Lightweight animated ASCII loaders, spinners and progress bars for web pages. One tag to embed, no images to download, honours reduced motion.