As I was adding a big unnecessary LCD screen to my new PC, I thought to myself 'Wouldn't it be cool if my PC could show an avatar that reacts to whatever my AI assistant is doing?'. The intrusive thought won, and turned into Eidola: a portable AI personality runtime with reactive avatars.
Three Core Components, One Runtime
Eidola is built around three core concepts:
The Soul is a SOUL.md file — pure personality prose. Voice, tone, rules, character. It's based on the soul.md open standard, which means it works anywhere that standard is supported. You inject it into AI context and the model has a persona.
The Vessel is the visual layer. An animated avatar that reacts to AI state. Vessels can be Three.js animations, Lottie files, WebM clips, or GIFs. You can map animation clips to specific expression states — when the AI is thinking, the Vessel shifts to the Thinking state. When it's working, it shifts to Working.
The Engram is the portable package. Soul plus Vessel, bundled into a downloadable directory. One artifact that captures the complete persona — the character and its face together.
As for the platform as a whole, Eidola (singular: eidolon) is a Greek word that means an unsubstantial image, phantom, or idealized mental representation of something, which could not be more fitting.
The Shrine
The Shrine is the display surface where the Vessel animations are displayed. Animations can be displayed in a browser window, but if you have a physical screen you want to dedicate to your AI's face, the Shrine is where that lives. The Shrine runs as a dedicated Electron window — frameless, chrome-free, taking over the screen entirely. No browser toolbar, no controls. Just the face. Display formats supported: Square (1:1), Circular (1:1), and Ultrawide (4:1).
Design Choices
Two design choices kept this from becoming a spaghetti codebase (so far).
First: scope to testable chunks. I wasn't sure exactly what I was building when I started, so scoping each piece to something concrete and testable kept the project tractable. I scoped out each feature as a distinct phase using my phase-runner skill, resulting in clear documentation for each build phase.
Second: build on established standards. The soul.md format handles Soul interoperability. The Engram package format borrows from existing plugin and persona distribution conventions. Building on top of these instead of inventing my own meant compatibility across platforms without maintaining a compatibility layer.
Animation States
The hardest design question so far has been how many expression states to support.
Originally, I started with a state for every granular AI action — working, thinking, writing, reading, and more. In practice, the states switched so fast that each animation barely played before the next one triggered. It felt too jittery and chaotic.
The fix: reduce the top-level mappable states to 8.
Idle · Thinking · Waiting · Working · Responding · Success · Error · Attention
Within states like Working, the UI still surfaces the specific tool calls — grepping, reading, writing — as sub-labels. The core animation switches less frequently, so it feels smoother. You still see exactly what the AI is doing, just without the animation whiplash.
What's Next
Eidola Directory + Plugin (coming soon)
I want to make the platform available to other users, and in doing so create a directory where users can create, download, and publish Eidola and Vessel packs (animations).
Animation Refinement
The animation transitions still aren't perfect. Making state changes feel good — smooth without being slow, responsive without being jittery — is harder than picking the right number of states. The 8-state model is a better answer than where I started, but it's not the final answer.
Claude Support
I built Eidola to work with the Cursor IDE first, since that is the tool that I was using to build the project, and the tool that I use most. However I want to extend support to Claude Code, which exposes different tool states than Cursor.
Emotional Classifier (longer term)
In the current version of Eidola, the Vessel animation states map directly to what the AI is doing (idle, thinking, waiting, etc), but it has no bearing on the actual conversation between the user and the AI. As an extension to the current platform, an emotional classifier system could infer the emotional tone of the conversation itself, and then output a state (happy, sad, confused, etc) that can be mapped to an animation state.