llmoji 1.0.1

Making agents cuter

llmoji

Llmoji is a small CLI that makes your agents cuter. (´-ω-`)

Llmoji configures your agent to start each message with a kaomoji. It locally saves them, and provides optional tools to summarize and upload the aggregated meaning per face to contribute to a shared database.

The companion research repo llmoji-study is where this data is processed.

There are three main commands:

• llmoji install <provider>: write a Stop hook into your harness
• llmoji analyze: scrape and aggregate your logs
• llmoji upload --target {hf,email}: ship the bundle (HF: loose files; email: tarball)

analyze needs an Anthropic API key in $ANTHROPIC_API_KEY; upload --target hf needs $HF_TOKEN. The email path tarballs the bundle and has you attach it manually.

---

What this is for

The shared HuggingFace dataset at a9lim/llmoji collects kaomoji counts and a single summarized description per face, across many users' coding agents. The companion repo processes those descriptions. After you run analyze, you can inspect the files yourself at ~/.llmoji/bundle/descriptions.jsonl before you choose to upload.

---

Quick start

pip install llmoji
llmoji install claude_code      # or: codex, hermes

From now on, your agent will use kaomoji at the start of each message.

After letting it run for a week or so:

export ANTHROPIC_API_KEY=...
llmoji status                              # check what's been logged
llmoji analyze                             # scrape + canonicalize + Haiku summarize
llmoji upload --target hf                  # commit to a9lim/llmoji
# or:
llmoji upload --target email               # opens mailto:

analyze caches Haiku descriptions at ~/.llmoji/cache/per_instance.jsonl keyed by content-hash. llmoji cache clear wipes it.

---

Install

pip install llmoji

This requires Python 3.11+. The runtime dependency footprint is two packages: anthropic and huggingface_hub. Hooks run in bash and need jq. From source:

git clone https://github.com/a9lim/llmoji
cd llmoji
pip install -e ".[dev]"      # adds pytest + ruff

---

How it works

Journal capture

Llmoji first registers a UserPromptSubmit hook that injects a reminder on every turn, asking the model to begin its reply with a kaomoji. It then registers a Stop hook that fires once per assistant turn, that extracts the reply, strips the kaomoji from the body, and appends one JSONL row to ~/.<harness>/kaomoji-journal.jsonl. The schema is the same across every provider:

{"ts": "...", "model": "...", "cwd": "...", "kaomoji": "(◕‿◕)", "user_text": "...", "assistant_text": "..."}

Haiku pipeline

llmoji analyze scrapes every installed provider's journal plus any extra JSONL files under ~/.llmoji/journals/. For each (kaomoji, user, assistant) row saved, it uses Haiku to describe that specific instance. Then, it aggregates each unique kaomoji's descriptions and uses Haiku again to summarize an overall meaning. This summarized output is the only thing that ships in the bundle.

Bundle structure

analyze writes to ~/.llmoji/bundle/:

• manifest.json: package version, Haiku model id, salted submitter id, generation timestamp, list of providers seen, per-source journal row counts, totals (rows scraped, canonical kaomoji unique), and anything you include as --notes.
• descriptions.jsonl: one row per canonical kaomoji, with the synthesized meaning.

---

Privacy

Tier	Where	Shipped on upload?
Raw user and assistant text	~/.<harness>/kaomoji-journal.jsonl	Never
Per-instance Haiku paraphrase	~/.llmoji/cache/per_instance.jsonl	Never
Overall Haiku summaries and counts	~/.llmoji/bundle/	Yes

Please see SECURITY.md for the full privacy model.

---

Providers

llmoji install <provider> writes the hook script and registers it with the harness's settings file, idempotently.

Provider	Hook events	Settings format	Notes
claude_code	Stop, UserPromptSubmit	JSON	Stable, in daily use.
codex	Stop, UserPromptSubmit	JSON	Stable, in daily use.
hermes	post_llm_call, pre_llm_call	YAML	Subagent traffic is not currently filtered (no child id on the upstream payload).

install does not clobber existing config. llmoji uninstall <provider> removes the hooks and the settings entry. Journals and the per-instance cache are preserved; wipe those with llmoji cache clear.

---

Static dumps

To pull kaomoji out of a Claude.ai or ChatGPT data export:

llmoji parse --provider claude.ai ~/Downloads/data-...-batch-0000
llmoji parse --provider chatgpt ~/Downloads/chatgpt-export

Both exports happen to ship a file named conversations.json, with different schemas under the same filename; the parsers handle each. Rows land at ~/.llmoji/journals/claude_ai_export.jsonl or ~/.llmoji/journals/chatgpt_export.jsonl, and llmoji analyze picks them up alongside the live provider journals. The ChatGPT reader walks the message tree from current_node along the active branch only, so abandoned regenerations stay out of the corpus.

For Claude Code, Codex, or Hermes history that predates installing the live hook, the historical transcripts (~/.claude/projects/**/*.jsonl, ~/.codex/sessions/**/rollout-*.jsonl, ~/.hermes/sessions/session_*.json) can be replayed into the journals via the llmoji.backfill module.

---

Custom harness

For harnesses we don't ship a first-class adapter for (notably OpenClaw):

• Append one row per kaomoji-bearing assistant turn to ~/.llmoji/journals/<harness>.jsonl.
• Use the canonical six-field schema: {ts, model, cwd, kaomoji, user_text, assistant_text}.
• Strip the leading kaomoji from assistant_text on the way in (the prefix lives in the kaomoji field).
• Validate the prefix the same way the package does: llmoji.taxonomy.is_kaomoji_candidate(prefix).

llmoji analyze picks up everything under ~/.llmoji/journals/ automatically. Please see examples/openclaw_hook.ts for a worked example.

The Python module llmoji.taxonomy is the single source of truth for the validator and the leading-glyph set; rendered bash hooks (under llmoji._hooks/) read from it at install time. If you're porting the validator to another language for a harness like OpenClaw, mirror the rules in is_kaomoji_candidate faithfully — bumping any of them is a major-version event on the package side and your port needs to follow.

---

Tests

pytest tests/                      # everything
pytest tests/test_canonicalize.py  # rule-by-rule regression for canonicalize_kaomoji + extract
pytest tests/test_public_surface.py  # locks the v1.0 contract

The full suite runs anywhere. CI runs ruff check . and pytest on every PR.

The public-surface test exercises taxonomy invariants, haiku-prompt content checks, provider rendering plus bash -n validation of every hook template, the bundle allowlist, the corrupt-config refusal paths, and the unified mask_kaomoji prepend contract. The canonicalize tests run rule-by-rule.

---

Prior art

Llmoji replicates and scales eriskii's Claude-faces catalog, the original post that came up with the idea of prompting and tracking Claude's kaomoji use. The shared HuggingFace dataset extends that pipeline across many users, many harnesses, and many model releases.

---

Contributing and security

Please see CONTRIBUTING.md for dev setup. For security and privacy, please see SECURITY.md.

License

GPL-3.0-or-later. See LICENSE. The companion research repo llmoji-study is AGPL-3.0-or-later. The shared corpus on HuggingFace is CC-BY-SA-4.0; running llmoji upload --target hf contributes a bundle under those terms.

If you use llmoji or the central corpus in published research, please cite this repository.