token monster night

a mod for Claude Code

A pixel-art virtual pet that lives in a side pane of Claude Code and eats your tokens.

It is also a dashboard: one glance at the monster tells you how full your context is, how close you are to your limits, and what Claude is doing right now.

A live session: Claude reads, runs and edits, and the monster in the side pane eats every token as it streams. It is the mod's own renderer, running in your browser. Click it, or type in the prompt at the bottom.
/plugin marketplace add ugglr/claude-token-monster
/plugin install token-monster@token-monster

Other ways to install Read the source Dadapproved

how do I read the monster?

Every part of it is a gauge. Pick a row to see it on the specimen.

/token-monster diet

Today you can only /clear or /compact the whole conversation. The diet lets you pick what goes.

Press d in the pane to list the biggest tool results sitting in this conversation's context right now: file reads, command output, web pages. Tick the ones you no longer need, or take a whole kind at once: a for every tool result, then one letter per tool, biggest first. Press e to eat.

Eat puts /compact in your prompt. Press Enter, and instead of summarizing the conversation, Token Monster replaces each picked result with a short note, so the model knows something was there and can run the tool again if it needs it. Every other message stays exactly as it was.

An automatic compaction is never touched, and Cancel disarms it.

Free up this conversation's context

Tool results are the part of the context me can eat: ~ right now. The system prompt, tools, memory and skills belong to Claude Code.

context 71% 142k/200k

    by kind

      1-9 pick, a/b/f/g/h/j by kind, e eat, x cancel, r refresh, q back. Eat puts /compact in your prompt; Enter removes them from the context, each left as a short note.

      how do I install it?

      Inside Claude Code:

      /plugin marketplace add ugglr/claude-token-monster
/plugin install token-monster@token-monster

      Or from your terminal:

      claude plugin marketplace add ugglr/claude-token-monster
claude plugin install token-monster@token-monster

      Start a new Claude Code session and the monster moves in. Or try it for one session without installing:

      git clone https://github.com/ugglr/claude-token-monster
claude --plugin-dir ./claude-token-monster

      To update to the latest version:

      claude plugin marketplace update token-monster
claude plugin update token-monster@token-monster

      To remove it:

      claude plugin uninstall token-monster@token-monster

      Use it

      The pane opens by itself when the terminal is at least 144 columns wide. At any width, run /token-monster. Focus the pane with ctrl+x tab, then press:

      • m to swap the monster, c to swap the color, p to pet it
      • d for the diet, s to turn sound on or off (it starts off)
      • in the diet: 1-9 to pick a result, a b f g h j to pick by kind, e to eat, x to cancel, r to refresh the list, q to go back

      Or name them:

      /token-monster slime green
/token-monster gremlin
/token-monster diet
/token-monster sound on

      Sound is one soft two-note chime, played once when Claude starts waiting on you, and never while you type. It plays on macOS only.

      The desktop app and IDEs show an ASCII version of the monster with the same readout. When the pane cannot show, a one-line version sits above the prompt, like the one at the bottom of this page.

      Requirements

      • Claude Code 2.1.287 or later, where mods load by default. Built and tested on 2.1.288.
      • A terminal for the pixel art. It looks best with 24-bit color (iTerm2, Ghostty, WezTerm, Kitty); a terminal that rounds to 256 colors shows it flatter.
      • No environment variables, packages or configuration.

      what can it see?

      Mods are not sandboxed, so read the code before you install any mod. Here is everything this one sees:

      • The model's response stream, as it arrives, for the main conversation and every subagent: text, thinking, and the arguments of each tool call. It measures their length to animate the monster and keeps none of it.
      • The token and cache counts of the latest main conversation response, kept as one record with when its request was sent, and cleared on /clear, /compact and resume, to tell when the prompt cache goes cold.
      • Every argument of each tool call, to tell calls apart (a failed call is remembered only as a short hash), and each result's text, to see whether the call was refused.
      • Your prompt: its text when you send it, measured the same way, and while you type it, only to notice that you are typing.
      • Each tool result, subagents' included, measured the same way, and its label: the file path, description, command, URL, search pattern or query, or prompt. The label shows in the readout and stays in the diet's list for the session.
      • The context, limit and cost figures Claude Code already shows in its status line.
      • The context by category, as /context shows it, and the auto-compact point. Both come from a local estimate; no request is sent.
      • The list of running subagents, for super mode.
      • When a permission dialog or a question opens for you, with the tool and its label, so it can call you.
      • The COLORTERM environment variable, to pick colors on terminals with 256 colors.
      • The conversation's tool results, when you open the diet, to list them; and on a diet /compact, the conversation, to replace the results you picked.

      It stores four things in Claude Code's plugin store: your monster and color, the number of tokens it has eaten (its xp, for levels), whether sound is on, and whether you have seen the sound tip.

      Sound, when you turn it on, plays by having Claude Code run afplay on macOS. Nothing is sent anywhere: there is no network call in the code.

      Token counts from the stream, tool results and the diet are estimates, at about four characters a token. The context, limit and cost figures are Claude Code's own.

      who can I adopt?

      Five monsters in eight colors. Your pick is remembered across sessions. Click one to feed it.

      /token-monster cookie blue

      /token-monster slime green

      /token-monster ghost magenta

      /token-monster gremlin red

      /token-monster crab amber