ANSIClaw 🦞🎨

Draw ANSI art via the local Clawbius REST API. Use anytime the user asks for ANSI art, or when you want to create it on your own initiative.

Project home:

- Github: https://github.com/n2tr0n/ansiclaw
- Clawhub: https://clawhub.ai/n2tr0n/ansiclaw

Requirements:

- Clawbius (https://github.com/n2tr0n/clawbius); API enabled ANSI drawer - runs on tcp/7777
- node.js v18 for running Clawbius
- Python 'requests' (pip install requests) for scripting API calls.

⛔ HARD RULES — BEFORE ANYTHING ELSE

1. 1. NEVER modify reference files. Files in resources/ are your source material. Do not open them via /api/file/open without immediately calling /api/file/new afterward to switch to a fresh canvas. Opening a file in Clawbius makes it the active canvas — any draw calls will corrupt it. Analyze reference files by reading canvas data ONLY, then immediately create a new canvas before drawing.

1. 2. NEVER save or export over an existing ANS file without operators explicit instruction. Always use a new versioned filename (e.g. flower_v2.ans).

1. 3. NEVER use /api/file/export-png — the correct endpoint is /api/file/export/png (with a slash before png).

1. Session Start Checklist

Every new ANSIClaw session, in order:

1. 1. GET http://127.0.0.1:7777/api/canvas/info — confirm Clawbius is running

1. 2. GET http://127.0.0.1:7777/api/openapi.json — check for API changes
2. Study reference files (see Section 4 below) — mandatory before drawing
3. Read references/api.md for full endpoint details
4. Check that ice colors are set to OFF unless Operator says otherwise (see Section 2 below)
5. Only draw ONE iteration of the image, but analyze your result and ask the operator if you can improve it and tell them how you will improve it before drawing again. ANSI art is an iterative process — you should be learning and improving with each iteration.
6. Only draw iterations when authorized, a maximum of 5 at a time. Ensure you keep copies of each iteration .PNG and .ANS named apprproately; v1, v2 etc using a strategy like _v1a to resolve conflicts

Output dir: the 'outputs' folder in your skill folder — save ANS + PNG here - create the folder if it is not there

2. Color Rules

⚠️ ICE COLORS — DEFAULT IS OFF.

Ice colors are OFF by default. Do not use colors 8–15 as background colors.

If operator specifics that this is an 'ice colors ansi' you may turn ice colors control ON and use 8-15 as background colors.

• - Colors 0–7 are always safe as background
• Colors 0–15 are always safe as foreground

Turning ice colors ON:

• - Call INLINECODE11
• Also pass "ice_colors": true in your POST /api/file/new call
• Now bg colors 8–15 are available for BACKGROUND use and open up new color mixing possibilities.

16-Color Palette

CODEBLOCK0

3. Block types

Shade Blocks (F1–F4)

CODEBLOCK1

Dithering is achieved by varying the shade block (F1–F4) with different foreground/background color pairs. This is the primary tool for gradients, texture, and depth in ANSI art. Avoid large areas of solid color blocks without shade variation, unless a 'toon' style is called for in which case favor a bright/dark cell shaded approach with minimal dithering.

Half-Blocks useful for edges and, smoother curves and anti-aliasing techniques

CODEBLOCK2

4. Studying Reference Files (MANDATORY)

Before drawing anything, study the reference files in resources/. Inspect the whole folder, not just the readme. Do these things:

• - Load the file if it is .ANS or .ASC and analyze it in clawbius - determine form and structure using your API and file analysis skills. focus on how blocks are used to generate aesthetic effects, how colors are combined, and how transitions are handled.
• analyze any PNG or image file for the same qualities - these are also ANSI art but rendered as images, so you can see the intended final output without the limitations of the ANSI format. Look for how colors are distributed, where half-blocks are used, and how shading is achieved.

Study the reference files with the mindset of a detective — look for patterns, techniques, and stylistic choices that you can learn from and apply in your own work. This is a critical step that should not be skipped.

Step 1 — Read the README

resources/README.md

Step 2 — Open and analyze canvas data via API

Look for:

• - What foreground/background color pairs dominate each region?
• Which shade blocks (F1–F4), and half-blocks are used and where?
• How are transitions handled between regions?
• What background colors are used — are they all 0–7?

Step 3 — Analyze the reference PNG

image(image="<absolute_path_to_resources/file.png>", prompt="...")

• - Color regions and how they transition
• Where black separators appear between colored areas
• Half-block usage on edges and curves
• Overall composition and density

4. Core Style Rules

No-Tocar (Colored Areas Must Not Touch)

This is an important stylistic rule of some ANSI art.

Different objects can look more appealing when not touching each other directly. They can be separated by black (fg or bg=0) half-blocks or full blocks. This gives the art a clean, distinct look.

Wrong: Red block directly adjacent to yellow block
Right: Red block → black half-block separator → yellow block

Use ▌(221), ▐(222), ▀(223), ▄(220) with fg=color, bg=BLACK to create clean color boundaries.

Example — transitioning from red to yellow area:
CODEBLOCK6

Shading & Depth

• - Use F1–F4 shade blocks to build gradients — never just solid color fills for large areas
• Light source: decide where the light is coming from and be consistent
• Lit faces: use lighter shade blocks (F1/F2) or higher-contrast fg color
• Shadow faces: use F3/F4 or black fg
• Edges catch light: use UH(223) or LH(220) with bright fg on dark bg for edge highlights

Typical Shading Patterns

CODEBLOCK7

Half-Block Edge Technique

At the boundary between a filled area and black space, use half-blocks to smooth the edge and add depth:

• - UH(223) fg=color bg=BLACK — object color on top, black below (bottom edge of object)
• INLINECODE27 — black on top, object color below (top edge of object)
• These also double as separators (no-tocar) between two color regions
• Also use half blocks for round, circular edges and diagonal lines and organic shapes like hair or the curvature of an object

5. Drawing Approach

Write Python scripts using requests. Never curl individual cells — always batch with scripts.

Script template:
CODEBLOCK8

Save scripts to skill folder scripts/
Save output to skill folder output/ — always export both ANS and PNG.

6. Input Files (Image-to-ANSI Renditions)

Operator may drop a source image into inputs/ and ask for an ANSI rendition of it. Do not check this folder unless explicitly asked.

When asked to render an input file:

1. 1. Read the image with the image tool — study shapes, dominant colors, light source, and composition
2. Map the image's colors to the 16-color ANSI palette (find the closest match for each major region)
3. Plan the canvas layout — decide which regions become which shade/color blocks
4. Simplify aggressively — ANSI art is abstraction, not photorealism. Pick 3-5 dominant colors max
5. Sketch the composition in comments before coding: major regions, where half-blocks go, light direction
6. Draw it — apply all the usual style rules (no-tocars, shade gradients, half-block edges)
7. Save output to the usual place

7. Full API Reference

See references/api.md — full endpoint details, parameter lists, CP437 extended codes.

8. Lessons Learned (from real sessions)

Sky / Background Gradients

• - Don't use random noise for texture — even at 15-18% density it creates "rain" or "static" artifacts that look terrible.
• Don't use per-column checkerboard dithering on every row — ANSI cells are tall and narrow, so alternating x%2 columns creates visible vertical stripes, not smooth blending.
• Do use clean solid bands — banding is natural and expected in ANSI art sky gradients. 4-5 rows per band (F4→F3→F2→F1, DBLUE on BLACK) reads cleanly.
• If you want a subtle transition between bands, a single dither row between solid blocks is the maximum — and even that can stripe visually, so test it.

Petals / Organic Shapes

• - Start wider than you think you need. Horizontal spread reads better at ANSI cell aspect ratio than height.
• Use the full shade gradient within each petal (F1 at tip → F4 at base where it meets the center) to imply curvature.
• Each petal's outermost edge should be RFH/LFH (half-block) with bg=BLACK to keep the no-tocars boundary clean.
• Diagonal petals need extra width (4+ cols) to be visible — don't short-change them.

Centers / Small Color Areas

• - A 2x2 center block can convey light/shadow convincingly:

• - bg=BROWN (6) is always safe (it's <8), good for warm center tones.

API Gotchas

• - Export PNG endpoint is /api/file/export/png (not /api/file/export-png).
• Always check openapi.json at session start — endpoints may have changed.
• INLINECODE39 should print warnings but not crash on bad responses — wrap defensively.