agent-ascii

v1.1.0

Published

a month ago

Convert images and GIFs into terminal ASCII art with a native Go CLI exposed through npx.

0High
0Medium
0Low

vinniai

ascii ascii-art cli gif image braille npx

agent-ascii

release-downloads

Convert images and GIFs into ASCII art in your terminal. Available on Windows, Linux and macOS — no Go required via npx.

Supports both ASCII character maps and braille patterns. Optimized for rendering UI screenshots, web pages, and photos.

Inspired by ascii-image-converter by Zoraiz Hassan.

Supported input formats: JPEG · PNG · BMP · WEBP · TIFF · GIF

Installation

npx

Run directly without installing:

npx agent-ascii ./image.png

The package downloads a prebuilt OS-specific binary on first run. No Go installation required.

npm Global Install

npm install --global agent-ascii

Then run:

agent-ascii ./image.png

GitHub Action

- uses: Vinniai/agent-ascii@v1
  with:
    paths: |
      examples/screenshots/apple-mobile.png
      examples/screenshots/google-desktop.png
    flags: --width 72
    output-dir: .agent-ascii-out

By default the action saves .txt artifacts with --only-save.

Agent Skill

bash <(curl -fsSL https://raw.githubusercontent.com/Vinniai/agent-ascii/main/scripts/install-skill.sh)

Manual install target:

bash <(curl -fsSL https://raw.githubusercontent.com/Vinniai/agent-ascii/main/scripts/install-skill.sh) --dir "$HOME/.codex/skills"

Go

go install github.com/Vinniai/agent-ascii@latest

Release Binaries

Download for your platform from the releases page, extract, and copy to your PATH:

# macOS / Linux
sudo cp agent-ascii /usr/local/bin/

# Windows — place agent-ascii.exe in a directory on your PATH

Examples

Most examples below use real screenshots from examples/screenshots/. Decrease terminal font size or increase width for best quality.

HTML layout (wordmark diff)

Two minimal pages in examples/webpage/ render the agent-ascii wordmark in JetBrains Mono (Google Fonts):

| File | Layout | |------|--------| | agent-ascii-basic.html | Title centered in the viewport | | agent-ascii-top-third.html | Same styling; title in the upper third (grid-template-rows: 1fr 2fr) |

Take screenshots at 800×1200, run with --layout, then compare the saved text outputs:

npm run example:webpage

This runs scripts/example-webpage-diff.sh: headless Chrome screenshots → examples/webpage/captures/*.png (gitignored) → braille layout with --layout --negative --dither → *-ascii-art.txt (gitignored) → unified diff examples/webpage/layout-diff.txt (checked in).

Without Chrome: open each HTML file in a browser, save full-page captures as captures/basic.png and captures/top-third.png, then follow the manual steps in examples/webpage/README.md (same diff --text flow).

Basic ASCII (`--width 80`)

agent-ascii examples/screenshots/apple-desktop.png --width 80

Complex character range (`--complex`)

Uses a wider ASCII character set for more tonal detail.

agent-ascii examples/screenshots/apple-desktop.png --width 80 --complex

Braille (`--braille`)

Uses Unicode braille patterns — terminal must support UTF-8.

agent-ascii examples/screenshots/apple-desktop.png --width 80 --braille

Braille + dither (`--braille`; dither on by default)

Dithering spreads pixel error across neighbors, giving sharper edges in braille mode. Dithering is enabled by default with --braille (-D / --dither; use --dither=false to match the previous off-by-default behavior).

agent-ascii examples/screenshots/apple-desktop.png --width 80 --braille

Layout mode (`--layout`)

Optimized for inspecting UI screenshots and web pages — auto-selects braille with adaptive contrast and dithering.

agent-ascii examples/screenshots/apple-desktop.png --width 80 --layout

Negative (`--negative`)

Inverts the character density, useful for light-background images.

agent-ascii examples/screenshots/apple-mobile.png --width 60 --negative

Custom character map (`--map`)

Define your own character gradient from darkest to lightest.

agent-ascii examples/screenshots/apple-mobile.png --width 60 --map " .-=+#@"

Braille + dither on mobile (`--braille`)

agent-ascii examples/screenshots/x-mobile.png --width 60 --braille

CLI Usage

Tip: Decrease font size or zoom out your terminal for maximum quality.

agent-ascii [image paths/urls or piped stdin] [flags]

Piped input is also supported:

cat myImage.png | agent-ascii -

Flags

| Flag | Short | Description | |------|-------|-------------| | --color | -C | Display in original image colors (requires 24-bit/8-bit terminal) | | --color-bg | | Apply color to character background instead of foreground | | --braille | -b | Use Unicode braille characters instead of ASCII | | --dither | -D | Apply dithering for braille conversion (default: on; no-op without --braille; --dither=false to disable). Short -d is --dimensions, not dither. | | --threshold N | | Braille on/off threshold (0–255, default: 128) | | --layout | | Optimize for UI/webpage screenshot inspection | | --complex | -c | Extended ASCII character range for more detail | | --map "chars" | -m | Custom character gradient, darkest to lightest | | --grayscale | -g | Grayscale output | | --negative | -n | Invert colors | | --width N | -W | Output width in characters (maintains aspect ratio) | | --height N | -H | Output height in characters (maintains aspect ratio) | | --dimensions W,H | -d | Explicit width and height in characters | | --full | -f | Fill terminal width | | --flipX | -x | Flip horizontally | | --flipY | -y | Flip vertically | | --save-img path | -s | Save as PNG to path | | --save-txt path | | Save as text file | | --save-txt-history | | With --save-txt, write *-ascii-art-latest.txt and overwrite a dotfile .*-ascii-art.history with the previous run’s text (same stem each time; no growing append). Git-friendly: ignore the dotfile. Default on when CI is set; use --save-txt-history=false for overwrite-only *-ascii-art.txt | | --diff-vs-last | | With --save-txt-history, print a unified diff vs the previous snapshot to stderr | | --diff-last-fail | | With --save-txt-history, exit 1 when the new output differs from the previous snapshot (CI gate; combine with --diff-vs-last to see the diff) | | --save-gif path | | Save GIF as ASCII art GIF | | --save-bg R,G,B,A | | Background color for saved images (RGBA) | | --font path | | Font .ttf file for saved images | | --font-color R,G,B | | Font color for output and saved images | | --only-save | | Skip terminal output when saving | | --formats | | Show supported input formats |

Comparison / diff

Compare two rendered outputs with a unified diff (similar to git diff). ANSI escape sequences are stripped before diffing so line changes stay readable when using --color. If the raw strings differ only in styling, a notice is printed to stderr while the exit code stays 0 (stripped text matches).

Exit codes: 0 = same after stripping ANSI, 1 = different, 2 = error.

Two images (or URLs) — same flags apply to both conversions; --save-* and --only-save are ignored for diff:

agent-ascii diff examples/screenshots/apple-desktop.png examples/screenshots/apple-mobile.png --width 40

Two saved text files (e.g. from --save-txt --only-save):

agent-ascii diff --text ./out/before-ascii-art.txt ./out/after-ascii-art.txt

For an end-to-end demo (HTML wordmark pages → screenshots → saved ASCII → examples/webpage/layout-diff.txt), see HTML layout (wordmark diff).

Tracked snapshots over time — with --save-txt and --save-txt-history (on by default under CI), each run overwrites *-ascii-art-latest.txt and overwrites .<name>-ascii-art.history with the prior run’s text (one slot per stem, not an append log). Previous output for diffing is taken from latest, then legacy numbered *-ascii-art-*.txt if present, then legacy *-ascii-art.txt, then the history dotfile (plain text; older append-only history files are still read for migration). Use --diff-vs-last for a git-style unified diff on stderr, and --diff-last-fail to fail when output drifts.

Automation

Three automation surfaces ship with this repo:

| Surface | Path | Purpose | |---------|------|---------| | GitHub Action | action.yml | Reusable action for CI and PR workflows | | Agent Skill | skills/agent-ascii/SKILL.md | Public skill for AI agent setups | | Agent Rules | AGENTS.md | Contributor and in-repo agent guidelines |

Use screenshots in examples/screenshots/ for repeatable smoke tests in CI.

Library Usage

go get -u github.com/Vinniai/agent-ascii/aic_package

package main

import (
	"fmt"
	"github.com/Vinniai/agent-ascii/aic_package"
)

func main() {
	flags := aic_package.DefaultFlags()
	flags.Width = 80
	flags.Braille = true
	flags.Dither = true

	asciiArt, err := aic_package.Convert("myImage.png", flags)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Print(asciiArt)
}

Note: For headless environments (web servers, CI), set at least one of flags.Width, flags.Height, or flags.Dimensions — terminal size detection won't be available.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

agent-ascii

Table of Contents

Installation

npx

npm Global Install

GitHub Action

Agent Skill

Go

Release Binaries

Examples

HTML layout (wordmark diff)

Basic ASCII (--width 80)

Complex character range (--complex)

Braille (--braille)

Braille + dither (--braille; dither on by default)

Layout mode (--layout)

Negative (--negative)

Custom character map (--map)

Braille + dither on mobile (--braille)

CLI Usage

Flags

Comparison / diff

Automation

Library Usage

Packages Used

License

Basic ASCII (`--width 80`)

Complex character range (`--complex`)

Braille (`--braille`)

Braille + dither (`--braille`; dither on by default)

Layout mode (`--layout`)

Negative (`--negative`)

Custom character map (`--map`)

Braille + dither on mobile (`--braille`)