amoji

Emoji/sticker manager for AI agents — collect, create, and search custom stickers stored locally.

Installation

Global (recommended for CLI use)

npm install -g amoji

After installation, the amoji command is available everywhere:

amoji list
amoji search "happy"

Local (as a library)

npm install amoji

const { getStickers, searchStickers } = require("amoji");

Prerequisites

Node.js >= 20 on a standard platform (Windows / macOS / Linux, x64 or arm64).
better-sqlite3 ships prebuilt binaries for all supported Node versions — no build toolchain needed in normal use.

If you are on an uncommon CPU architecture or running Node from source, the native module may need to fall back to compilation:

| Platform | Fallback requirement | |---|---| | Windows | Visual Studio Build Tools with "Desktop development with C++" workload | | macOS | Xcode Command Line Tools: xcode-select --install | | Linux | build-essential + python3: sudo apt install build-essential python3 |

Development setup

git clone https://github.com/MMMarcinho/amoji.git
cd amoji
npm install
npm run build
npm link          # makes `amoji` available globally from source

Or run directly without installing:

npx tsx src/index.ts <command>

Stickers are stored in ~/.amoji/ (images in ~/.amoji/images/, ASCII art in ~/.amoji/ascii/, database at ~/.amoji/stickers.db).

Commands

Add stickers

Add an image file:

amoji add <name> <file> [-k keywords] [-d description]

amoji add thumbsup ~/Downloads/thumbsup.png -k "approve,yes,good" -d "strong approval"

Create ASCII art interactively:

amoji ascii <name> [-k keywords] [-d description] [-r rows] [-c cols]

amoji ascii shrug -k "whatever,meh" -d "indifferent shrug"

Use arrow keys to move the cursor, Space/Enter to draw, 1–9/0 to pick a block character, C to clear a cell, X to clear all, S to save, Q to quit without saving.

Import ASCII art from a text file:

amoji ascii shrug -f path/to/art.txt -k "whatever,meh"

Find stickers

Search by name, keywords, or description:

amoji search <query>

amoji search "happy"
amoji search "approve good"

List all stickers (optionally filtered by type):

amoji list
amoji list --type ascii
amoji list --type image

List all keywords with usage counts:

amoji keywords

Recently used:

amoji recent [-n limit]     # default 10

Most used:

amoji popular [-n limit]    # default 10

Use a sticker

Show sticker content (and mark as used):

amoji show <name|id>

For ASCII stickers this prints the art to stdout. For image stickers it prints the absolute file path.

Show metadata only (does not increment usage count):

amoji info <name|id>

Mark as used and get structured output:

amoji use <name|id>            # file path + metadata
amoji use <name|id> --base64   # also returns base64 data URI (images only)

Outputs structured key:value lines:

• file:<absolute-path> — always present
• type:image|ascii — always present
• name:<name> — always present
• count:<n> — usage count after marking
• base64:<data-uri> — only with --base64 on image stickers
• ─── separator followed by raw ASCII art (ASCII only)

Edit stickers

Set or replace keywords:

amoji tag <name|id> <keywords>

amoji tag thumbsup "approve,yes,great"

Append keywords:

amoji tag thumbsup "perfect,nice" --append

Set description:

amoji desc <name|id> <text>

amoji desc thumbsup "enthusiastic approval or agreement"

Delete a sticker

amoji delete <name|id>

Removes both the database record and the file from ~/.amoji/.

Sticker IDs

Every sticker has a numeric ID. Most commands accept either the name or the ID:

amoji show 3
amoji info thumbsup
amoji delete 7

Tips

• Names must be unique. If you add a sticker with a name that already exists, a timestamp is appended automatically.
• FTS (full-text search) is used for search. If it returns nothing, a LIKE fallback runs automatically.
• show and use both increment the usage counter; info does not.
• use --base64 encodes the image file on the fly and outputs a data URI — convenient for embedding in HTML/markdown without a separate file server.