# Installation

Add the asciicn engine and agent skill to a shadcn project, or install a single component or background.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. The asciicn agent skill, for building any ASCII effect on the engine, is at [/.well-known/agent-skills/asciicn/SKILL.md](/.well-known/agent-skills/asciicn/SKILL.md).

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 [#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.

```text
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 [#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](https://ui.shadcn.com/docs/installation) 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 [#add-the-skill-with-the-skills-cli]

The [skills CLI](https://skills.sh) installs the skill into Claude Code, Codex, Cursor, Gemini CLI and other agents that read skills. Run it in your project:

```bash
npx 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 [#or-add-the-engine-and-the-skill-with-shadcn]

  ### Run the add command [#run-the-add-command]

  ```bash
npx shadcn@latest add https://asciicn.dev/r/asciicn-skill.json
```

  This writes:

  * `lib/ascii/`: the CPU engine (`ascii-core`), the WebGL2 glyph renderer (`ascii-shader`) and the export functions (`ascii-export`).
  * `.agents/skills/asciicn/` and `.claude/skills/asciicn/`: the agent skill. Claude Code reads `.claude/skills`; Codex, Cursor and other agents that follow the [Agent Skills](https://agentskills.io) layout read `.agents/skills`.
  * The `--ascii-*` CSS variables (`ascii-tokens`), in the CSS file named in your `components.json`.

  Commit the skill folders with the rest of your code, so everyone on the project, and every agent, gets the same skill.

  ### Check your CSS [#check-your-css]

  The CLI adds the variables for light and dark mode, and colour utilities to the `@theme inline` block:

  ```css
  @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;
    }
  }
  ```

  Because the variables point at your theme tokens, there is nothing extra to set for dark mode. [Theming](/docs/theming) lists every variable.

Then ask your agent for an effect. The [introduction](/docs#ask-your-agent-for-any-ascii-effect) has example requests and explains what the agent does with them.

## What's in the skill [#whats-in-the-skill]

| File                          | What it covers                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `SKILL.md`                    | The four steps the agent follows, how to choose a technique, and the rules for every effect                                           |
| `references/engine-api.md`    | The engine's exports: `AsciiShader`, `AsciiGrid`, `mapTones`, charsets, palettes, metrics, motion hooks and export                    |
| `references/fields.md`        | Writing a GLSL field: the `uv`/`res`/`t` contract, sub-sampled charsets, uniforms, pointer and audio input                            |
| `references/charsets.md`      | Choosing a charset and a colour mode for a picture, custom ramps, phosphors and duotone ramps                                         |
| `references/recipes.md`       | Complete components to adapt: a shader background, a CPU grid, a Braille trace, a terminal pane, an image, a full animated background |
| `references/landing-pages.md` | Designing the page around the effect: start from the product, one memorable hero, true copy, the tells to avoid                       |
| `references/placement.md`     | Layering, sizing, server and client components, text over glyphs                                                                      |
| `references/theme.md`         | The `--ascii-*` tokens, named colours, palettes, light and dark mode                                                                  |
| `references/export.md`        | Saving frames as text, ANSI, SVG and PNG, and recording WebM                                                                          |
| `references/quality.md`       | The checks: crisp glyphs, contrast, reduced motion, accessibility, performance                                                        |
| `references/examples.md`      | Every component and background, with its install command and docs link                                                                |

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 [#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:

```bash
for 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 [#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:

```bash
npx shadcn@latest add https://asciicn.dev/r/ascii-shader.json
```

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

```bash
npx shadcn@latest add https://asciicn.dev/r/tokyo.json
```

## Update the engine [#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:

```bash
rm -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 [#use-a-namespace]

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

```json title="components.json"
{
  "registries": {
    "@asciicn": "https://asciicn.dev/r/{name}.json"
  }
}
```

Then install with the `@asciicn` prefix:

```bash
npx shadcn@latest add @asciicn/asciicn-skill
npx shadcn@latest add @asciicn/tokyo
```

See the shadcn docs on [namespaced registries](https://ui.shadcn.com/docs/registry/namespace) for more options, including authentication.

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

## Next steps [#next-steps]

* [Ask your agent for any ASCII effect](/docs#ask-your-agent-for-any-ascii-effect) with the skill installed.
* Browse the [catalog](/docs/examples) or the [backgrounds](/backgrounds) for something to install as it is.
* Try a look in the [Studio](/studio) and export the JSX.
* [Write your own](/docs/engine/write-your-own) field, step by step.