# id-agent

> Token-efficient, human-readable word-based ID generator for AI agents — a UUID alternative optimized for LLM context windows.

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`.

## Features
- Word-based human-readable IDs optimized for LLM context windows
- Every word is exactly 1 BPE token on o200k_base tokenizer
- Configurable entropy from ~12 to ~192 bits (1–16 words)
- Random ID generation using CSPRNG (crypto.getRandomValues)
- Deterministic ID generation from string input via HMAC-SHA256
- Optional type prefix support
- Bidirectional alias map for UUID-to-word replacement in LLM prompts
- Duplicate ID detection via regex scanning
- Full ID parsing into prefix, words, entropy bits, and format
- Validation against the curated 4096-word WORDLIST
- Zod-powered schema validation on all public APIs
- Frozen immutable WORDLIST export
- TypeScript-first with full type definitions
- MIT licensed open-source

## Integrations
OpenAI (o200k_base tokenizer compatible), tiktoken, Zod, Web Crypto API, Node.js, Bun, npm

## Platforms
ANDROID, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v1.0.5

## Links
- Website: https://vostride.com/
- Documentation: https://github.com/vostride/id-agent#api-reference
- Repository: https://github.com/vostride/id-agent
- EveryDev.ai: https://www.everydev.ai/tools/id-agent