Skip to content

Disentangle clanker avatar from the pets subsystem #42

Description

@hai-pilgrim

Context

Clanker character avatars are currently implemented inside the upstream pets subsystem (codex-rs/tui/src/pets/). A clanker character's avatar is represented as pet = "custom:<name>" in configuration, and the rendering, animation, and lifecycle code all lives in the pets module alongside novelty pet animations (fox, cat, unicorn, etc.).

This creates several problems:

  1. Semantic mismatch. A clanker's avatar is its identity — not a decorative pet. The avatar should be a first-class character concept, not a pet variant.
  2. Coupling. Changes to the pet system (animation frames, sprite formats, positioning) unintentionally affect character avatars and vice versa.
  3. Naming confusion. Config fields like pet, types like PetWidget, and module paths like pets/ are misleading when the actual concept is "character avatar."
  4. Extensibility. Features like room composition (Room is a manifest field with no runtime: half-block room composition unimplemented #37), multi-agent avatar display (Disentangle clanker avatar from the pets subsystem #42), and voice playback animation (Voice workstream not started: clanker-voice plugin, Ears speech input, say output, playback animation #35) need avatar as a standalone concept, not entangled with pets.

What is needed

  1. Extract avatar as a standalone TUI concept. Create an avatar module (or similar) that owns character avatar rendering, animation, and state. The pet system can delegate to it or coexist separately.

  2. Rename the seam. Config fields, types, and module paths should use "avatar" (or "character avatar") terminology for clanker identity display. The pet concept can remain for novelty animations but should be clearly separated.

  3. Preserve backward compatibility. The upstream pet config and rendering must continue to work. This is an additive extraction, not a removal.

  4. Character manifest integration. The avatar should be loaded from the character manifest (CharacterManifestV1) rather than from pet configuration. The manifest already has avatar-related fields.

Relationship to existing issues

Acceptance criteria

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions