pixel.md

pixel.md is a small, dependency-free component library for AI and agent products. Add one useful pixel detail to the interface you already built.

Install

npm install pixel.md

Live gallery · npm · GitHub

The gallery lets you try every component and copy its individual usage snippet. Browser components are native Custom Elements; terminal helpers are separate Node.js functions. You add only the pieces you import.

Quick start

For a clean first install, start a small Vite app and add the package:

npm create vite@latest my-agent-ui -- --template vanilla
cd my-agent-ui
npm install pixel.md
npm run dev

Import only the components you use in src/main.js:

import 'pixel.md/indicator';
import 'pixel.md/chat-effect';

Place the elements in your existing index.html or app template:

<pixel-agent-status state="thinking" label="Thinking…" detail="Connecting ideas"></pixel-agent-status>

<pixel-chat-effect variant="orbit">
  <textarea placeholder="Ask anything…"></textarea>
</pixel-chat-effect>

This exact integration is available as a runnable Vite example. <pixel-chat-effect> adds a pixel treatment around your input; your app still owns the textarea, messages, and send behavior. Update the indicator's state, label, and detail from your real agent state.

Components

| Import | Element or API | Includes | | --- | --- | --- | | pixel.md/indicator | <pixel-agent-status> | Thinking, searching, browsing, reading, planning, acting, tool, building, verifying, and responding states | | pixel.md/chat-effect | <pixel-chat-effect> | Orbit, Hop, Anchor, Bevel, Tilt, Prism, Car, and Cat effects, with idle and working states | | pixel.md/elements | <pixel-ui-element> | 22 workflow elements, including voice states, jump-to-latest, and attachment upload/processing | | pixel.md/bot | <pixel-bot-avatar> | Eight animated pixel characters with configurable states and labels | | pixel.md/terminal | Node.js functions | ANSI-friendly prompts, progress, output, task lists, confirmations, and more | | pixel.md/terminal-preview | <pixel-terminal> | Browser preview of fourteen terminal patterns |

Import pixel.md to register all four browser elements at once, or use the individual subpaths above to keep imports explicit.

Copy one component

Every preview in the live gallery has a Copy code action. It copies that preview's import and usage only, so you can add a single component to your existing interface.

For example, add only a context meter to an existing Node.js CLI:

import { pixelMeter } from 'pixel.md/terminal';

console.log(pixelMeter('CONTEXT WINDOW', 68, {
  max: 100,
  columns: 16,
  rows: 2,
  tone: 'mint'
}));

Connect real agent state

Keep component state tied to the state machine in your app:

const status = document.querySelector('pixel-agent-status');

function setAgentState(state, detail) {
  status.setAttribute('state', state);
  status.setAttribute('detail', detail);
}

setAgentState('searching', 'Looking through project files');

Workflow elements emit a bubbling pixel-element-change event so your app can handle interactions:

document.querySelector('pixel-ui-element').addEventListener(
  'pixel-element-change',
  event => {
    console.log(event.detail.variant, event.detail.state);
  }
);

The package includes TypeScript declarations. Browser elements register when their entry point is imported; see the live gallery for interactive examples.

Terminal CLI

Use the Node.js entry point for terminal output and prompts. It has no runtime dependencies, respects NO_COLOR, and falls back to plain text when output is piped.

import { askPixelCommand, pixelOutput } from 'pixel.md/terminal';

const command = await askPixelCommand({ cwd: '~/project' });

// Validate the input before passing it to your own command runner.
if (command) {
  console.log(pixelOutput({
    command,
    lines: ['Build complete'],
    status: 'success',
    duration: '1.8s'
  }));
}

The terminal helpers format output and collect input; they do not execute shell commands. Your CLI remains responsible for validation and execution. Node.js 18 or newer is required for the terminal entry point.

Design principles

• Small by default. Pixel motion is a detail around the interface, not a replacement for it.
• Bring your own UI. Chat effects wrap existing inputs; they do not take over application state or interaction.
• Native browser elements. No React runtime or component framework is required.
• Motion with care. Animated browser components pause when hidden or offscreen and honor prefers-reduced-motion.
• Useful in a terminal. CLI output supports ANSI color, piped output, and NO_COLOR.
• No runtime dependencies. Browser elements and CLI helpers use platform APIs.

Agent skills

The package includes a general pixel-md catalog skill with references for indicators, chat effects, UI elements, bots, and terminal patterns, plus focused indicator, chat-effect, and UI-element skills. To add the general skill manually to a project:

mkdir -p .agents/skills
cp -R node_modules/pixel.md/skills/pixel-md .agents/skills/

For Claude Code, copy the same folder to .claude/skills/ instead. The skill is optional; the components work without it.

Install as a coding-agent plugin

The repository also provides a plugin marketplace for Codex and Claude Code. It installs the general catalog skill and focused indicator, chat-effect, and UI-element skills. The skills guide the agent; install pixel.md separately in the app when you want to use the runtime components.

Codex

codex plugin marketplace add JJongyn/pixel.md
codex plugin add pixel-md@personal

Claude Code

/plugin marketplace add JJongyn/pixel.md
/plugin install pixel-md@pixel-md

In Codex, the plugin is also listed in this repository's marketplace. In Claude Code, skills use the /pixel-md:... namespace. Refresh the marketplace to receive later plugin releases.

Examples and gallery

The npm package includes the examples in examples/. Browse and try all components in the live gallery. To run the gallery from a repository checkout:

python3 -m http.server 4173

Then open http://localhost:4173/.

Contributing

Bug reports, ideas, and pull requests are welcome. Please include the component or entry point involved and a short reproduction when reporting a problem.

• Open an issue
• Browse the source

License

MIT © 2026 JJongyn