glyphloop: Instructions file for Codex

Glyphloop - Agent Guide

This repo generates loop-perfect generative ASCII animations for websites. As an AI agent you can create one without a browser: author a small JSON preset, run one command (or use the MCP server), and drop the output files into a site.

Quick start (CLI)

npx glyphloop@beta render --preset flowfield-hero --out out/hero
npx glyphloop@beta render --json '{"sourceId":"waves","mapper":{"fg":"#00ff88"}}' --out out/waves

From a source checkout:

npm run render -- --preset flowfield-hero --out out/hero
npm run render -- --json '{"sourceId":"waves","mapper":{"fg":"#00ff88"}}' --out out/waves

Output (--format embed, the default):

File	Purpose
frames.json	RLE-compressed character frames + style metadata
player.js	Dependency-free player (~2 kB, honors prefers-reduced-motion)
index.html	Working demo page

Other formats: --format terminal (ANSI frames.ans + play.sh), --format frames (frames.json only). The command prints a JSON summary on success and a descriptive error: line on bad input - errors list the valid options, so read them and retry.

MCP server (use from any project)

npx glyphloop@beta mcp

From this repository, run npm run mcp. To register the installed command in Claude Code:

claude mcp add --scope user glyphloop -- npx -y glyphloop@beta mcp

Tools: list_sources (call first - full schema + params), preview_frame (render one frame as text to check the look before committing), and render_animation (write embed/terminal/frames files to a directory). Iterate: preview → tweak preset → preview → render.

Embedding in a website

<div data-ascii-player></div>
<script>window.ASCII_DATA = /* contents of frames.json */;</script>
<script src="player.js"></script>

Or call AsciiPlayer(element, data) yourself. The player renders into a <pre>; size with CSS font-size. Keep embeds modest: ~140 cols × 8–12 s × 24 fps is commonly 0.5–2.5 MB of frames.json depending on motion and RLE compression, and per-cell source color can be larger. Preview the actual export before shipping it on a performance-sensitive page.