Entity

A low-poly head with an open skull that watches Claude Code work.

Entity sending out five sub-agents

Entity puts a face on Claude Code. Every prompt, tool call, sub-agent and compaction plays out on a faceted head inspired by the opening of Beyond the Mind's Eye: in place of a brain, a cluster of atoms sends pulses of light through the open skull, and the corners carry live telemetry from your session.

It runs as a VS Code panel, or in a window of its own next to Claude Code in a terminal or the Claude desktop app.

Download: the standalone app (zip) · the VS Code extension (.vsix) · or Entity for Claude Code in the VS Code Marketplace. Earlier versions are on the Releases page.

What it does

When Claude…	the head…
gets a prompt	looks at you, then narrows its eyes and thinks; the cluster lights up
reads and searches (Read, Grep, Glob)	eyes darting, looking around; blue pulses
searches the web (WebSearch, WebFetch, a browser)	looks far off, past you; teal pulses
runs a command (Bash, PowerShell)	a grave, fixed stare, brows down; orange pulses
runs tests	holds its breath, lips pressed; breathes out and smiles when they pass, winces when they fail
fails at the same thing again	a deep breath, a deeper frown; relief when it works at last
commits or pushes	a proud nod and a smile
edits files	a focused look down; purple pulses
sends out a sub-agent	a smaller cluster flies out of the skull on a tether and roams round the head – up to its outline, never across it – each by its temper: the searcher (Explore) darts everywhere, the worker runs low, the planner hovers above, the inspector (review, tests) circles close, the watcher (logs) keeps to the top corners. It stops and scans whenever the agent uses a tool
a sub-agent finishes	the fragment flies home and merges with the brain; a background agent stays out until it really ends
a tool fails	a twitch, a red glitch
compacts the conversation	closes its eyes and lifts its head as in meditation, while a wave of facets runs across the face in time with its breath; violet pulses
needs your permission	raises its brows, looks straight at you and says so
asks you something (a question, a plan to approve)	tilts its head, leans in and waits for your answer
is thanked or praised	smiles
is interrupted (Esc)	a start – head back, eyes wide, a blink – then calm
is done	nods and rests; falls asleep halfway through the prompt-cache countdown
the session ends, or the cache runs out	meditates, then falls apart into shards, leaving a golden spark; your next prompt brings it back together



taking shape from shards, and falling apart again	compacting: a wave of facets, in time with its breath

asking you something	thanked

Getting started

VS Code

Install Entity for Claude Code from the Marketplace.
Click the Entity icon in the activity bar. On first start Entity asks to connect to Claude Code: choose Install hooks.
Start a new Claude Code session – in the terminal, the VS Code extension or the desktop app. The head takes shape with your first prompt.

The head is a VS Code view: drag it to the side bar, the secondary side bar or the panel by the terminal, and VS Code remembers where. Entity: Open in Editor Tab puts it next to your code or in a window of its own. If you lose it, click 👁 Entity in the status bar or run Entity: Show Head.

Without VS Code

Download the standalone app, unpack it anywhere and run Entity.cmd (Windows), Entity.command (macOS, double-click) or ./entity.sh (Linux). On its first start it connects to Claude Code, then opens a window without browser bars at http://localhost:5190 (Edge or Chrome in app mode). Any browser can open that address too – the browser panel of the Claude desktop app included.

Options: --port=5191, --no-open (only the server), --remove-hooks (disconnects Entity from Claude Code), --log (prints every event from Claude Code and what the head got).

macOS blocks a file downloaded from the internet the first time (unidentified developer): right-click → Open → Open; on macOS 15+ System Settings → Privacy & Security → Open Anyway; or once xattr -dr com.apple.quarantine <the Entity folder>.

The extension and the standalone window can run at the same time.

Requirements

Claude Code – the CLI, the VS Code extension or the desktop app.
Node.js 18+ to run the hooks (the Node.js inside VS Code can't be used for that). Without one, Entity offers to download its own: Node.js 24 LTS from nodejs.org, about 40 MB (60 MB on macOS/Linux), checked by SHA-256, into %LOCALAPPDATA%\Entity\node (~/.local/share/Entity/node). No admin rights; your PATH and everything else stay as they are.

Privacy

Everything stays on your computer.

The hooks start a small script in the background (async), so Claude Code never waits for it. It passes the event on to Entity at 127.0.0.1: what happened, the tool's name, the session, and a few flags – a command runs tests, a command commits, a prompt thanks or praises. Never the prompt, a command or a file's content. A sub-agent's type and the short description Claude gives it are passed on to label it.
Entity reads the session's transcript on your disk for the numbers in the corners and to see when sub-agents end.
No telemetry. The only download is the optional Node.js from nodejs.org, after you agree to it.

Connecting to Claude Code

Entity: Install Claude Code Hooks adds Entity's hooks to ~/.claude/settings.json; it saves a backup (settings.json.entity-backup) before every change and leaves your other hooks and settings alone. Entity: Remove Claude Code Hooks (or --remove-hooks) takes them out again – do that before you uninstall. A hook that gets lost is made up for within seconds from the session's transcript.

Older Claude Code. Before 2.1.101, Claude Code ignores the whole settings.json as soon as it finds a hook event it doesn't know. Entity asks claude --version and gives an older Claude Code only the events it knows (it then doesn't see tool failures, for one). After claude update, start Entity again and all of them are set.

The corners

top left – how full the context window is (CTX)
bottom left – output tokens and tools of the current request (REQ)
bottom right – how long the server keeps the conversation in its prompt cache (MEM). When the cache runs out and nothing is going on, the head dissolves; the next prompt brings it back.

Account limits only reach Entity through Claude Code's status line. Entity: Enable Claude Code Status Line sets ~/.claude/entity/entity-status.js as the status line: one row in the terminal (model, context, the 5-hour and weekly limits) and the same numbers for the head – top right what's left of the 5-hour session (SES) and when it resets (RST), bottom right the weekly limit (WK). Entity never replaces a status line of someone else's.

With several sessions, the head follows the one you last typed into; another takes over once that one is idle.

Voice

The head speaks a few lines in English or Czech (switch in the menu), with subtitles that type out even when the sound is off. Your own recordings with the same names in ~/.claude/entity/voice (Czech in cs/) take precedence – Entity: Open Voice Folder. VS Code lets a panel play sound only after it has been clicked once; until then the head speaks in subtitles.

Controls

Right-click the head for its menu: what it's doing, voice language, volume, talkativeness, the HUD, VHS, glow, grid, backdrop speed and the demo (Entity: Play Demo runs through all of the above). The D key shows the control panel with buttons for every event.

Setting
`entity.onlyThisWorkspace`	react only to sessions running inside this window's folders
`entity.statusBar`	the last Claude Code event in the status bar
`entity.voiceFolder`	a folder with your own voice recordings
`entity.showControls`	show the control panel on start

Development

npm install
npm run vendor
npm run preview

The preview runs at http://localhost:5180/?debug. Useful parameters: clean (no panel), still (the head holds still), zoom=2, orbit=90 (side view), lookX=-0.3, lookY=0.1, noeyes. npm run package builds the .vsix; npm run dist builds the extension and the standalone app (folder and zip) into distribuce/. A version tag (v1.0.7, matching package.json) makes GitLab build both and publish them as a release (.gitlab-ci.yml, tools/gitlab-release.js).

The head itself (media/js/head-mesh.js, head-shape.js) is generated from a detailed sculpt that is not part of this repository: tools/bake-shape.js fits it to anatomical measures and finds the skull cut, tools/build-head.mjs --tris=2600 opens the skull in square steps, cuts the eyes and lips and reduces it to about 2,600 flat triangles. node tools/export-stl.mjs exports the head as you see it.

Where	What
`media/js/sculpt-head.js`	the head: facets, jaw, brows, smile, shards, the compacting wave
`media/js/eyes.js`	eyeballs and lids
`media/js/brain.js`	the cluster in the skull and the sub-agent fragments
`media/js/behavior.js`	moods: what the head does on which event
`media/js/voice.js`	lines, playback, the jaw following the voice
`media/js/fx.js`, `background.js`	scan ring, HUD, the backdrop
`extension/core.js`	events in, shared by the extension and the standalone app: sessions, agents, transcripts
`extension/hooks-config.js`	Entity's entries in `~/.claude/settings.json`
`hooks/entity-hook.js`	the script Claude Code runs for each hook
`hooks/entity-status.js`	the optional status line
`standalone/entity-app.js`	the standalone app

Credits

Inspired by the opening of Beyond the Mind's Eye – the open-skull head, the telemetry in the corners, the cyan scan ring, the glitch. Built with three.js. Made by MTB, together with Claude.

License

MIT