Installation

asciicn installs with the shadcn CLI, like any other registry. One command adds the engine and the agent skill. After that you ask your agent for ASCII effects, or install components and backgrounds one at a time.

Quick start with your agent

Paste this prompt into Claude Code, Codex, Cursor or any other coding agent. It installs the engine and the skill, reads the docs and builds the effect you ask for. The home page copies the same prompt.

Add asciicn to this project and build me an ASCII effect with it.

1. Install the asciicn engine and agent skill with the shadcn CLI:
   npx shadcn@latest add https://asciicn.dev/r/asciicn-skill.json
   This writes lib/ascii (the glyph engine and its WebGL2 shader), the skill in .agents/skills/asciicn and .claude/skills/asciicn, and the --ascii-* CSS variables. The project needs shadcn/ui, Tailwind CSS v4 and React 19.
2. Read .agents/skills/asciicn/SKILL.md and follow it for everything below. If it isn't on disk, read https://asciicn.dev/.well-known/agent-skills/asciicn/SKILL.md. The docs are at https://asciicn.dev/docs, and https://asciicn.dev/llms.txt lists every page as Markdown.
3. If I haven't said which effect I want and where it goes, ask me in one question, and suggest two or three that would suit this project, each with a charset (Braille, ANSI blocks, katakana, CP437...).
4. Build the effect I asked for on the engine, coloured from my theme. The example components and scenes are references: install one only if it is exactly what I asked for. Otherwise write your own field on AsciiShader, or an AsciiGrid for CPU-drawn grids, and borrow technique from the closest example's source.
5. Check it in a browser in light and dark mode, at desktop and phone widths and with reduced motion. Glyphs must be crisp and text over them readable. Fix what doesn't read, then tell me what you made and where.

The rest of this page does the same steps by hand.

Before you start

You need a project that already uses shadcn/ui, with a components.json file, Tailwind CSS v4 and React 19. If you don't have one yet, follow the shadcn installation guide first. The GPU renderer needs WebGL2, which every current browser has; components show a static fallback where it's missing.

Add the skill with the skills CLI

The skills CLI installs the skill into Claude Code, Codex, Cursor, Gemini CLI and other agents that read skills. Run it in your project:

$ pnpm dlx skills add https://asciicn.dev

It asks which agents to install for, then writes the skill and its references into each agent's skills folder, such as .claude/skills/asciicn/ and .agents/skills/asciicn/. Add -g to install it for every project on your machine. The skill adds the engine to your project the first time your agent builds something with it.

Or add the engine and the skill with shadcn

Copy@theme inline {
  --color-ascii-ink: var(--ascii-ink);
  --color-ascii-paper: var(--ascii-paper);
  /* and one per named colour: --color-ascii-blue, --color-ascii-green, … */
}
 
@layer base {
  :root {
    --ascii-ink: var(--primary);
    --ascii-paper: var(--background);
    --ascii-cell: 12px;
    --ascii-glow: 0.35;
  }
  .dark {
    --ascii-ink: var(--primary);
    --ascii-paper: var(--background);
    --ascii-glow: 0.9;
  }
}

Then ask your agent for an effect. The introduction has example requests and explains what the agent does with them.

What's in the skill

The skill matches the engine it installs with and points your agent at the files in your project, so it never has to guess at an API.

Install the skill for every project

shadcn add writes the skill into the current project only. To make it available in every project on your machine, run the skills CLI with -g. Without the CLI, download the archive into your user skills folder:

Copyfor dir in ~/.claude/skills/asciicn ~/.agents/skills/asciicn; do
  mkdir -p "$dir"
  curl -fsSL https://asciicn.dev/.well-known/agent-skills/asciicn.tar.gz | tar -xz -C "$dir"
done

The skill tells the agent to install the engine into a project the first time it needs it.

Install the engine, a component or a background

Without the skill, install the engine on its own. ascii-core is the CPU side (charsets, AsciiGrid, mapTones); add ascii-shader for the WebGL2 renderer:

Or install any component or background. Each one brings the parts of the engine it uses on its first install:

Update the engine

The engine is plain source in your project, so it doesn't update on its own. Newer docs can use features your copy lacks: if TypeScript says a prop doesn't exist on AsciiShader or AsciiGrid, delete lib/ascii and add the engine again:

Copyrm -rf lib/ascii
npx shadcn@latest add https://asciicn.dev/r/ascii-core.json https://asciicn.dev/r/ascii-shader.json https://asciicn.dev/r/ascii-export.json

If the CLI asks whether to overwrite lib/utils.ts, answer no. Avoid --overwrite, which replaces that file too. If you edited any file in lib/ascii, copy your changes out first.

Use a namespace

To install by name instead of by URL, add asciicn to the registries field of your components.json:

Copy{
  "registries": {
    "@asciicn": "https://asciicn.dev/r/{name}.json"
  }
}

Then install with the @asciicn prefix:

bunnpmpnpmyarn
$ pnpm dlx shadcn@latest add @asciicn/asciicn-skill
npx shadcn@latest add @asciicn/tokyo
Copy

See the shadcn docs on namespaced registries for more options, including authentication.

Other ways in for agents

The skill is the main way in. The site also publishes plain-text surfaces for agents that browse:

• /llms.txt lists every docs page with a one-line description and a Markdown link, and /llms-full.txt is the whole documentation as one file.
• Add .md to any docs URL for its Markdown, for example /docs/installation.md, or send an Accept: text/markdown header. The home page, /studio and /backgrounds answer Markdown requests too.
• The registry index is at /r/registry.json, and each item at /r/<name>.json. The shadcn MCP server can browse and install from it once you have added the @asciicn namespace.
• /.well-known/agent-skills/index.json lists the skill archive with its SHA-256 digest, /.well-known/api-catalog links every machine-readable surface (RFC 9727), /openapi.json describes the read-only endpoints, and /api/v1/status returns {"status":"ok"}. The home page sends these as Link headers too.

Next steps

• Ask your agent for any ASCII effect with the skill installed.
• Browse the catalog or the backgrounds for something to install as it is.
• Try a look in the Studio and export the JSX.
• Write your own field, step by step.