This release introduces the first real foundation for **Buddy Companion**, a local animated presence that reacts to what Thoth is doing. It also improves model selection, Vision handling, and startup reliability on Linux and Windows. The focus is expression, clarity, and stability across the whole app.

[GitHub Repo](https://github.com/siddsachar/Thoth)

Below is a deeper breakdown for anyone who wants the technical details.

# Buddy Companion Foundation

Buddy now has a real subsystem behind it. This includes:

* a prompt‑generated Buddy architecture with a thread‑safe event bus
* a deterministic behavior brain
* persistent config and pack validation
* Hatch art and motion generation
* a canvas playback engine with effects
* one in‑app Buddy that lives in the sidebar
* a separate desktop overlay surface for systems that support it

Buddy listens to Thoth’s internal events. It reacts to chat streaming, thinking, tool calls, approvals, workflows, notifications, and voice state. The identity stays unified under Preferences so Buddy does not introduce a second name or persona. The UI focuses on state, personality, and motion.

A new route called `/buddy-overlay` supports the desktop Buddy window where native overlay helpers are available.

# Motion, Packs, and UI Polish

This release ships with bundled first‑party motion packs: glyph, lumen, ember, pixel, sprout, and orbit. Hatch‑generated custom packs are copied into Thoth’s served assets so they behave like native packs.

Key improvements:

* better prompts for Hatch generation so backgrounds, padding, and edges key cleanly
* smoother transitions between idle, thinking, working, approval, success, and error
* MP4 playback crossfades state changes and avoids jitter when loops restart
* idle motion replays periodically without looking busy
* Buddy can be dragged out of the sidebar and snaps back when released near the dock
* Buddy returns home on restart instead of remembering stray positions

Settings for Buddy now use a dense layout similar to the Models tab. Pack selection uses preview tiles and clears stale overrides when switching back to bundled packs.

# Hatch save and recovery

This part got a lot of attention:

* saving Buddy settings now preserves newly generated Hatch art and motion
* generated packs become selectable user packs
* still‑only art remains valid when motion generation fails
* users can delete generated packs
* motion retry regenerates from the selected still without overwriting the pack manifest
* new motion requests use provider‑compatible 5 second clips
* full Buddy generation runs as a background job with progress and notifications
* internal prompts stay private so user concepts do not turn into pose sheets
* transparent stills are composited onto a stable background before video generation
* older Hatch packs with overwritten manifests are recovered on load

Stopping a workflow immediately moves Buddy out of the running state.

# Desktop Overlay Reliability

The desktop Buddy overlay is more stable now:

* approval, denial, workflow, and error bubbles stay visible even in Quiet mode
* bubbles survive rapid state changes
* the overlay waits for the transparent document to paint before revealing
* fallback window creation paths help when transparency or hidden‑window hints fail
* startup guards prevent transient None values from crashing the overlay
* no more snapshot pushes into deleted NiceGUI clients

Workflow state cleanup is also more accurate. Denials, timeouts, cancellations, and stops clear Buddy’s workflow state immediately. Successful multi‑step workflows emit a clear done state.

# Models, Vision, and Settings Reliability

A lot of polish landed here:

* Settings loads the provider catalog lazily and caps rows so huge catalogs do not crash
* timers clean up properly when clients disconnect
* local Ollama chat models appear even when their family is not in Thoth’s curated lists
* Brain and Vision pickers now make it clear that catalog rows must be pinned first
* Codex Vision pins keep their image‑input capability during Quick Choice refreshes
* Codex Responses transport preserves multimodal image blocks
* Vision model changes are validated against Quick Choices, local models, and provider catalogs
* invented or unavailable model names are rejected with actionable guidance

There is now an explicit vision\_model setting.

# Linux and Startup Reliability

Linux users get a much more predictable startup path:

* the launcher resolves symlink chains correctly so `~/.local/bin/thoth` always starts the right version
* packaged launches report startup log tails and child process exit details
* `THOTH_STARTUP_TIMEOUT` is configurable
* clearer hints for missing or broken native dependencies like OpenCV, FAISS, or NumPy
* camera and screenshot capture degrade gracefully instead of blocking startup

Installer UX is also improved. Source builds support a simple `bash build_linux_app.sh <version>` command. Success messages now mention `~/.local/bin/thoth` when the bin directory is not on PATH. Maintainer docs now distinguish unreleased tarball testing from the one‑line installer path.

Optional native packages like TorchCodec are detected and logged with concrete recovery commands. Transformers treats broken optional packages as unavailable instead of letting them crash startup.

# Windows repair hardening

The Windows installer now replaces the embedded Python runtime during repair or upgrade. This prevents corrupted or manually installed packages from surviving an over‑the‑top reinstall.

# Summary

v3.21.0 brings:

* a real Buddy Companion foundation
* cleaner motion, better UI, and more reliable generation
* clearer model and Vision selection
* stronger Linux startup and better diagnostics
* safer Windows repair behavior

It is a mix of expression, stability, and quality of life improvements across the entire app.

Thoth v3.21.0 - Buddy Companion, Model Picker Improvements, and Stronger Linux Startup