Changelog

Install an update with npx skills update -y. The face window restarts itself on the new version the next time the agent uses it.

0.2.2 — 2026-10-05

• Fix: speech was cut off by a state change. Any redraw of the face — a new state (an agent's end-of-turn update, often right after say), a template switch, or a file changing in .agent-face/ — stopped the clip being spoken. Now the voice plays to the end, the clip's words stay up, and the mouth carries on with the new state's frames. Only another clip cuts it off.
• status says when the face is speaking: speaking, and ms_left while it is.

0.2.1 — 2026-10-05

• Fix: clips could play silently. The face kept one audio connection open for its whole life, and a speaker that slept, reconnected or changed could leave it playing to nowhere, while say still said played and the mouth moved. Each clip now opens the speakers that are current at that moment, and closes them when it ends.
• say reports where the sound went: an audio object with the output's state, the device, sample rate and latency, plus the face's volume. If the output doesn't start, say fails with an error instead of claiming it played.
• sound-test plays a short chirp through the same path and reports the same details. The voice skill now has steps for "the user can't hear you".
• Every clip played (or failed) is written to the face's log.

0.2.0 — 2026-10-05

The face folder moved, and now holds several templates. Templates live in .agent-face/<template>/ in the agent's repo; 0.1 kept a single face in agent-face/. To carry a face over, make it a template:

mkdir .agent-face
git mv agent-face .agent-face/<id>     # plain "mv" if the folder isn't tracked

Until that's done, face commands fail with a hint saying exactly this. A window left open by 0.1 is closed automatically when the face next starts. The window's position, mute and volume start fresh.

• Templates. templates lists them, use <template> switches (so does the window's right-click menu), and init --template <id> adds a starter one. states, clips and check take --template <id>, so an agent can list the states and voice clips of any template.
• current returns the face as it is now — template, state, caption — with a PNG of it for the agent to show in the chat.
• Resizable by dragging. Drag any edge or corner; scrolling still works. The window keeps the image's shape.
• Really always on top. The face now stays in front of other always-on-top windows instead of being covered by them.

0.1.0 — 2026-10-05

First version. Three skills that replace the Agent Face MCP app:

• agent-face — the face window (Electron: transparent, always on top, draggable, scroll to resize) and the face.cjs command: setup, init, start, stop, status, states, state, random, caption, clips, say, check, snapshot.
• agent-face-voice — speaking clips with lip-sync; mute and volume stay with the user.
• agent-face-template — the face folder format, a checker, and a starter face generated by code.

The face lives in agent-face/ in the agent's own repo and is re-read live. Window position, mute and volume live in ~/.agent-face/. The agent talks to the window over a local pipe; there is no server and no port.