agent-shader

English | 日本語

Build Panzoid Shader Object JSON, validate Panzoid fragment shaders, and render-test them in a real WebGL 1 context.

This repository contains three independently installable pieces:

• agent-shader: an npm CLI for validation, JSON generation, rendering, and tests
• agent-shader MCP server: the same capabilities exposed as local MCP tools
• panzoid-shader: a portable Agent Skill for generating shaders that follow the Panzoid conventions

The core model is intentionally static. Generated Panzoid parameters use animated: false and one value at frame zero; animation and keyframe inputs are not accepted. A build writes JSON only after validation, Chromium WebGL 1 compilation and rendering, four-background premultiplied-alpha checks, and RGB-only diagnostics. An unchanged default produces a warning but does not block a valid build.

Requirements

• Node.js 22 or later
• npm
• Chromium installed through the included Playwright command for rendering and render tests

Quick start

Install the CLI globally and download its Chromium runtime once:

npm install --global agent-shader
agent-shader install-browser

Then install the skill for the coding agents detected on your machine:

npx skills add rbstxt/agent-shader --skill panzoid-shader -g

Finally, configure the MCP server in your agent. The standard stdio configuration is:

{
  "mcpServers": {
    "agent-shader": {
      "command": "npx",
      "args": ["-y", "agent-shader@latest", "mcp"]
    }
  }
}

CLI

Global installation

npm install --global agent-shader
agent-shader install-browser

Run without a global installation

npx -y agent-shader@latest install-browser
npx -y agent-shader@latest validate shader.glsl

Commands

agent-shader validate fixtures/circle.glsl
agent-shader build fixtures/circle.glsl --out circle.json
agent-shader render fixtures/circle.glsl --out circle.png
agent-shader test fixtures/circle.glsl --out-dir circle-test

Every nonstandard numeric uniform requires an explicit, deliberate default. Prefer one that demonstrates the behavior clearly, but an unchanged default is valid when it is intentional and appropriate. Use --config config.json for those defaults or for explicit ranges:

{
  "name": "Soft Circle",
  "parameters": {
    "Radius": {
      "default": 0.25
    }
  }
}

Standard parameters are optional and inferred without configuration only when their matching uniforms are declared. Treat them as opt-in controls, not a mandatory bundle. For effects that draw a distinct object or shape, generally add Position, Rotation, Scale, and Opacity so the user can control placement, orientation, size, and overall visibility; omit an individual control only when it has no meaningful effect. Opacity is not required merely for source-over compositing.

| Uniform | Type | Default | Bounds | | --- | --- | --- | --- | | Color | vec3 | [1, 1, 1] | omitted | | StartColor | vec3 | [1, 1, 1] | omitted | | EndColor | vec3 | [1, 1, 1] | omitted | | Opacity | float | 1 | 0..1 | | Position | vec2 | [0, 0] | omitted | | Rotation | float | 0 | omitted | | Scale | vec2 | [1, 1] | omitted |

The only required shader inputs are tDiffuse and vUvScaled. Color, StartColor, EndColor, Opacity, Position, Rotation, and Scale may all be omitted independently. A full-screen screen-space effect, such as an image/UV warp or distortion, normally needs none of Position, Rotation, Scale, or Opacity; modify vUvScaled or calculate the effect internally instead. The generated customProperties array contains only uniforms actually declared by the shader.

The test command renders the default X-Y grid, opaque black, transparent black, and a semi-transparent color. Every render also gets an RGB-only diagnostic PNG that exposes RGB hidden behind alpha. It checks premultiplied-alpha invariants and reports whether the default differs visibly from the unmodified input. If it does not, default-no-visible-change is emitted as a warning and the test may still pass; the agent decides whether the unchanged default is intentional and appropriate. If the shader declares Progress, it additionally renders 0.00, 0.10, 0.35, 0.65, 0.90, and 1.00. The agent must inspect every applicable normal and RGB-only PNG before handing off the JSON.

min and max are authoring decisions, not automated render tests. Do not add them merely to describe an intended, conventional, or useful range. Set a bound only when changing the value farther beyond that point produces no additional visual change; otherwise omit it. Opacity uses 0..1 because generated shaders clamp it and values outside that range therefore cannot change the result.

There is one intentional exception: set min to 0 for a magnitude-only parameter when negative values merely reverse or mirror the same size behavior instead of providing a meaningfully distinct control. The standard Position, Rotation, Scale, and color parameters remain unbounded.

Shader Object names are short and effect-specific. When config name is omitted, the CLI and MCP infer one from the shader filename, such as glowing-ring.glsl → Glowing Ring. An explicit config name always wins; a generic filename falls back to Effect rather than Shader.

Image uniforms

Each additional uniform sampler2D Name; becomes this Panzoid custom property, with properties.name exactly matching the GLSL uniform:

{
  "type": {
    "custom": true,
    "type": 8,
    "assetType": 0,
    "accept": "image/*",
    "value": null
  },
  "properties": { "name": "Name" },
  "value": null
}

Provide images for rendering as a JSON map:

{
  "Landscape": "/absolute/path/to/landscape.jpg"
}

agent-shader test fixtures/texture-blend.glsl \
  --config fixtures/texture-blend.config.json \
  --textures textures.json \
  --out-dir texture-test

Rendering

Rendering launches Chromium through Playwright and requests a WebGL 1 context with antialiasing disabled. It uses the Panzoid common.glsl contract, a 16:9 canvas by default, uvScale = [1, 1], and a deterministic Python-generated X-Y grid as tDiffuse. Extra image samplers use the bundled CC0 landscape unless overridden with --textures or MCP texturePaths. See samples/ATTRIBUTION.md for provenance.

Shader output uses premultiplied-alpha source-over. Do not divide RGB by the resulting alpha:

float sourceAlpha = clamp(effectAlpha, 0.0, 1.0);
vec4 texel = texture2D(tDiffuse, vUvScaled);
float backgroundAlpha = clamp(texel.a, 0.0, 1.0);
float remainingBackground = backgroundAlpha * (1.0 - sourceAlpha);
float outputAlpha = sourceAlpha + remainingBackground;
vec3 outputColor = effectColor * sourceAlpha + texel.rgb * remainingBackground;
gl_FragColor = vec4(outputColor, outputAlpha);

Here effectAlpha and effectColor are values computed by the effect. If Opacity is declared, multiply the internal alpha by clamp(Opacity, 0.0, 1.0); otherwise compute source alpha internally. If Color is omitted, compute the effect color internally or from a sampled texture. Do not add controls only to match the example.

On vec4(0.0) input this reduces to vec4(effectColor * sourceAlpha, sourceAlpha). The validator rejects division by outputAlpha and direct unpremultiplied source output. Tests require zero hidden RGB at alpha zero and RGB attenuation with alpha. When Opacity is present, they also require input preservation at Opacity = 0; for colors in 0..1, they normally require R <= A, G <= A, and B <= A.

GLSL ES 1.00 compatibility

Panzoid Shader Objects run as WebGL 1 / GLSL ES 1.00. The validator allows #define, function-like macros, #if, #ifdef, #ifndef, #elif, #else, and #endif. GL_ES, GL_FRAGMENT_PRECISION_HIGH, and __VERSION__ == 100 are available for conditional compilation.

The only allowed optional extension is:

#extension GL_OES_standard_derivatives : require
precision highp float;
precision highp int;

Use that declaration before precision statements whenever dFdx, dFdy, or fwidth is used. The validator rejects every other #extension, #version, #include, glslify pragmas, discard, texture2DLodEXT, texture2DGradEXT, gl_FragDepthEXT, and gl_FragData.

AA is omitted unless the user explicitly requests it. That choice belongs to the agent workflow rather than static validation; derivatives remain available for patterns, normal estimation, change measurement, and analytical effects.

Comments and resolution-like identifiers produce advisory warnings rather than validation errors. Agents normally omit them, but may keep them when the user explicitly requests them or the effect genuinely needs them. The validator does not require a recognizable clamp(Opacity, 0.0, 1.0) expression; Opacity handling is left to shader authoring and render verification.

agent-shader render shader.glsl \
  --out render.png \
  --width 1920 \
  --height 1080 \
  --uv-scale 1,1 \
  --values values.json \
  --input source.png

Install from source

git clone https://github.com/rbstxt/agent-shader.git
cd agent-shader
npm ci
npm run install-browser
npm run build
npm link

After npm link, the agent-shader and agent-shader-mcp executables are available locally.

Before the npm release, point an MCP client directly at the built server:

{
  "mcpServers": {
    "agent-shader": {
      "command": "node",
      "args": ["/absolute/path/to/agent-shader/dist/src/mcp.js"]
    }
  }
}

Agent Skill

The skill is stored at .agents/skills/panzoid-shader. The skills CLI discovers that standard directory directly from GitHub.

GitHub is sufficient for skill distribution. The skill itself does not need to be published to npm: npx downloads the npm-published skills installer, and that installer fetches panzoid-shader from this GitHub repository.

Automatic installation

Let the installer detect your coding agents and prompt for the destinations:

npx skills add rbstxt/agent-shader --skill panzoid-shader -g

Install globally for every supported agent without prompts:

npx skills add rbstxt/agent-shader --skill panzoid-shader --agent '*' -g -y

Omit -g to install into the current project instead of the user-level skill directory.

Install for a specific agent

Codex

npx skills add rbstxt/agent-shader --skill panzoid-shader -a codex -g -y

Claude Code

npx skills add rbstxt/agent-shader --skill panzoid-shader -a claude-code -g -y

OpenCode

npx skills add rbstxt/agent-shader --skill panzoid-shader -a opencode -g -y

Command Code

npx skills add rbstxt/agent-shader --skill panzoid-shader -a command-code -g -y

Other agents

The installer supports Cursor, Cline, Gemini CLI, GitHub Copilot, Kiro CLI, Qoder, Windsurf, Warp, and many more. Run the interactive command, or replace the value after -a with an agent identifier from the skills supported-agent table.

npx skills add rbstxt/agent-shader --skill panzoid-shader

MCP server

The MCP server exposes:

• build_shader_object
• validate_shader
• render_shader
• test_shader

build_shader_object returns JSON only after its complete automated verification pass and includes all normal and RGB-only previews so the agent can inspect the four required inputs and every applicable Progress checkpoint.

Rendering tools require the one-time browser installation:

npx -y agent-shader@latest install-browser

Skill installation and MCP installation are separate. Install both when you want the agent to have the Panzoid conventions as well as deterministic build and render tools.

MCP client configuration

The client examples below follow the layout and conventions used by Chrome DevTools MCP. If a client accepts the standard MCP JSON, use:

{
  "mcpServers": {
    "agent-shader": {
      "command": "npx",
      "args": ["-y", "agent-shader@latest", "mcp"]
    }
  }
}

Add the server with the Codex MCP CLI:

codex mcp add agent-shader -- npx -y agent-shader@latest mcp

Equivalent ~/.codex/config.toml configuration:

[mcp_servers.agent-shader]
command = "npx"
args = ["-y", "agent-shader@latest", "mcp"]

Add the server at user scope with the Claude Code MCP CLI:

claude mcp add agent-shader --scope user npx -y agent-shader@latest mcp

Add this to ~/.config/opencode/opencode.json as described in the OpenCode MCP guide:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-shader": {
      "type": "local",
      "command": ["npx", "-y", "agent-shader@latest", "mcp"]
    }
  }
}

Add the server at user scope with the Command Code MCP CLI:

cmd mcp add agent-shader --scope user npx -y agent-shader@latest mcp

amp mcp add agent-shader -- npx -y agent-shader@latest mcp

Open the custom MCP server settings described in the Antigravity MCP documentation and use the standard JSON configuration above.

Follow the Cline MCP configuration guide and use the standard JSON configuration above.

Start copilot, run /mcp add, select a local server, and enter:

• Server name: agent-shader
• Command: npx -y agent-shader@latest mcp

Use the Command Palette command MCP: Add Server, or run this on macOS and Linux:

code --add-mcp '{"name":"io.github.rbstxt/agent-shader","command":"npx","args":["-y","agent-shader@latest","mcp"],"env":{}}'

For Windows PowerShell:

code --add-mcp '{"""name""":"""io.github.rbstxt/agent-shader""","""command""":"""npx""","""args""":["""-y""","""agent-shader@latest""","""mcp"""]}'

Open Cursor Settings → MCP → New MCP Server, then use the standard JSON configuration above.

devin mcp add agent-shader -- npx -y agent-shader@latest mcp

droid mcp add agent-shader "npx -y agent-shader@latest mcp"

Project scope:

gemini mcp add agent-shader npx -y agent-shader@latest mcp

User scope:

gemini mcp add -s user agent-shader npx -y agent-shader@latest mcp

Follow the Gemini Code Assist MCP guide and use the standard JSON configuration above.

grok mcp add agent-shader npx -y agent-shader@latest mcp

For AI Assistant, open Settings | Tools | AI Assistant | Model Context Protocol (MCP) and add the standard configuration. For Junie, use Settings | Tools | Junie | MCP Settings.

Open Kiro Settings → Configure MCP → Open Workspace or User MCP Config, then use the standard JSON configuration above.

Install an MCP proxy, then expose the stdio server over Streamable HTTP:

mcp-proxy --transport streamablehttp --port 8080 -- npx -y agent-shader@latest mcp

Configure StudioAssist with http://127.0.0.1:8080/mcp and the HTTP transport. Choose another port if 8080 is already in use.

Add this to ~/.vibe/config.toml:

[[mcp_servers]]
name = "agent-shader"
transport = "stdio"
command = "npx"
args = ["-y", "agent-shader@latest", "mcp"]

Open Qoder Settings → MCP Server → + Add, then use the standard JSON configuration above.

Project scope:

qodercli mcp add agent-shader -- npx -y agent-shader@latest mcp

User scope:

qodercli mcp add -s user agent-shader -- npx -y agent-shader@latest mcp

Open the MCP server configuration UI and use the standard JSON configuration above with npx as the command.

Open Settings | AI | Manage MCP Servers → + Add, then use the standard JSON configuration above.

Follow the Windsurf MCP configuration guide and use the standard JSON configuration above.

For any other MCP client, select a local or stdio server and use npx as the executable with these arguments:

-y
agent-shader@latest
mcp

Verify the MCP installation

Ask the agent:

Use agent-shader to validate and render-test fixtures/circle.glsl, then show the render and summarize any diagnostics.

The agent should call test_shader; it should return all normal and RGB-only PNGs in addition to the JSON report.

Development

npm ci
npm run install-browser
npm run check
npm test

License

MIT