id-agent

id-agent is an open-source TypeScript library published on npm by Vostride AI that generates word-based identifiers designed specifically for use inside LLM context windows. Where UUID v4 costs roughly 23 BPE tokens and is prone to hallucination, id-agent produces hyphen-separated English-word IDs at around 14 tokens with comparable collision resistance. The project was featured on Hacker News and reached v1.0.5 as of May 2026.

What It Is

id-agent is a UUID alternative built for the agentic era. Instead of hex strings that BPE tokenizers split unpredictably, it draws words from a curated 4096-word list where every word is exactly one BPE token on the o200k_base tokenizer (used by GPT-4o, GPT-4.1, o1, and o3). The result is IDs that are both human-readable and significantly cheaper to include in prompts. The library is written in TypeScript, validated with Zod, and uses crypto.getRandomValues() (CSPRNG) for random IDs and HMAC-SHA256 via the Web Crypto API for deterministic IDs.

Core API Surface

The library exposes several focused primitives:

• idAgent(opts?) — generates a random word-based ID; configurable word count (1–16) and optional type prefix
• idAgent.from(input, opts?) — deterministic ID from a string input using HMAC-SHA256; supports namespace scoping
• parse(id) — deconstructs an id-agent ID into prefix, words, word count, entropy bits, and format
• validate(id) — checks whether a string is a valid id-agent ID and reports unknown words or casing errors
• createAliasMap(opts) — bidirectional alias map for replacing long IDs (e.g., UUIDs) with short word aliases before sending text to an LLM, then restoring originals from the output
• detectDuplicates(opts) — scans text or arrays of strings for repeated IDs using a regex pattern
• WORDLIST — direct access to the frozen 4096-word array

Token Efficiency and Entropy Math

The library's wordlist is sized at exactly 4096 words (2¹²), so each word contributes 12 bits of entropy regardless of character length. The default 8-word ID yields ~96 bits of entropy — safe for over 300 trillion items before a 50% collision probability. Shorter configurations trade entropy for token savings: a 5-word ID uses ~8 tokens and is safe to roughly 1 billion items, while a 3-word ID uses ~5 tokens and suits development or short-lived contexts. The token savings versus UUID v4 range from 26% (10 words) to 78% (3 words), with the default 8-word format saving approximately 39%.

Why It Matters for Agent Workflows

LLM agents frequently pass IDs through prompts, tool calls, and memory stores. UUID v4's ~23-token cost accumulates quickly in multi-step agentic pipelines, and hex strings are more likely to be hallucinated or corrupted by models. id-agent addresses both problems: word-based IDs are memorable to models and humans alike, and the createAliasMap utility lets developers transparently compress existing UUID-heavy text before it enters the context window and restore originals afterward.

Update: v1.0.5

The latest release is v1.0.5, published on 20 May 2026. The repository was created in April 2026 and has seen active iteration since launch. The project is MIT-licensed, hosted at github.com/vostride/id-agent, and distributed via npm as id-agent.