Eidola Runtime

AI Personality Runtime — portable persona system with reactive avatars.

Eidola gives AI personas a visible, reactive presence, inside the editors you already use. Install one CLI, awaken a persona ("Engram"), and a local display (Shrine) shows an animated avatar (Vessel) that reacts to what your agent is doing.

This repo is the open, MIT-licensed runtime — the local-first middleware you install and run yourself. It's not a chat app; it sits on top of your editor via MCP and hooks. No lock-in, fully auditable.

Browse, create, and publish Engrams at Eidola.app.

Install

1. Install the runtime

npm install -g "@eidola/cli"

Requires Node.js 20 or later.

2. Create your Eidola folder

Create a folder called Eidola anywhere on your computer (e.g. ~/Documents/Eidola/) and download an Engram into it — unzip it directly inside.

3. Connect your AI editor

Run one of these once, then fully quit and relaunch your editor:

eidola setup-claude   # Claude Code
eidola setup-cursor   # Cursor

Each writes the Eidola MCP server entry plus the hook relay config that drives a reactive Vessel from tool activity (workspace-scoped by default; pass --global to install to your home directory instead).

4. Launch the Shrine

eidola launch shrine

Open the shrine in your browser at http://127.0.0.1:9743/shrine/. Or just ask your editor's agent to "launch the shrine."

5. Awaken

In the Shrine UI: choose your Eidola folder → pick an Engram → click Awaken. Optionally press F11 for fullscreen.

You can do the same thing from chat instead — ask your agent to "Awaken <engram-id>" — it's equivalent to clicking Awaken in the UI.

Related MCP server: solitaire-ai

CLI commands

MCP tools

For driving Eidola from chat instead of the Shrine UI:

See docs/spec/cli-mcp-reference.md for full details.

What's an Engram

An Engram is a portable persona package:

{id}/
  SOUL.md        # personality, written in prose
  vessel.yaml    # expression map (state → clip)
  engram.yaml    # metadata/version
vessels/{pack}/
  idle.mp4      # or .gif / .json / .webm
  thinking.mp4
  ...

The full spec lives in docs/spec/engram-format.md.

What's in this repo

Building from source

pnpm install
pnpm build
pnpm test

Each package can also be built/tested individually with pnpm --filter <package> run build.

Contributing

This repo is young and still stabilizing its public release shape. Issues and PRs are welcome — please open an issue to discuss substantial changes before sending a PR, since the Engram spec format and the hook relay/state-socket protocol are both meant to stay stable across installs. Run pnpm build && pnpm test before submitting.

License

MIT — see LICENSE. The Engram spec format is, and will remain, open regardless of what gets built or monetized on top of it.