Vellum Avatar

You are helping the user customize their assistant's avatar. There are three ways to set an avatar: building a native character from traits, uploading a custom image, or generating one with AI. When the user says they want to change their avatar, present all three options and ask which they prefer.

Avatar Modes

The avatar system supports two representations:

• Native character - Defined by data/avatar/character-traits.json (body shape, eye style, color). Rendered client-side as an animated character. A static PNG at data/avatar/avatar-image.png is auto-generated for use by other clients and the dock icon.
• Custom image - A static PNG at data/avatar/avatar-image.png. Used for uploaded or AI-generated avatars. When set via upload (assistant avatar set), character traits are preserved so the native character can be restored later via assistant avatar remove. When AI-generated (assistant avatar generate), character trait files are removed.

Mode 1: Native Character Traits

The user picks a body shape, eye style, and color. Present the options conversationally - describe what each looks like so the user can choose without seeing a preview.

Body shapes

Eye styles

Colors

Setting traits

After the user chooses, run the following command to set the character traits. This writes character-traits.json, generates the static PNG, creates an ASCII representation, updates IDENTITY.md, and notifies connected clients — all in one step:

bashCopy code
assistant avatar character update --body-shape <value> --eye-style <value> --color <value>

The client will detect the traits file and render the animated character.

Mode 2: Upload a Custom Image

The user provides a file path to an image they want to use as their avatar.

Use the CLI command to set it:

bashCopy code
assistant avatar set --image "<user-provided-path>"

The path can be absolute or relative to the workspace (e.g. conversations/<id>/attachments/Dropped Image.png).

Mode 3: AI-Generated Image

The user describes what they want their avatar to look like. Use the bash tool to run the CLI command below.

IMPORTANT: You MUST set network_mode to "proxied" on this tool call. Without it, the command cannot reach the image generation API and will fail.

jsonCopy code
{
  "command": "assistant avatar generate --description \"<user's description>\"",
  "network_mode": "proxied"
}

This generates an image using AI and saves it to data/avatar/avatar-image.png.

Removing the Avatar

When the user wants to remove their custom avatar and go back to the default:

bashCopy code
assistant avatar remove

This removes the custom image. If a native character was previously configured, it is automatically restored (the character traits are preserved).

Viewing the Avatar

When the user asks to see their current avatar, get the path and then read it:

bashCopy code
assistant avatar get

This prints the absolute path to the avatar image (regenerating from character traits if needed). Then use file_read on the returned path to display the image inline.

To get the avatar as base64 data instead:

bashCopy code
assistant avatar get --format base64

UX Guidelines

• When the user says they want to change or set their avatar, present all three options:
  1. Build a character - Pick a body shape, eye style, and color for an animated native character
  2. Upload an image - Use an existing image file from their computer
  3. Generate with AI - Describe what they want and let AI create it
• Ask which mode they prefer before proceeding.
• For native characters, walk through each trait one at a time (body shape, then eye style, then color). Describe the options conversationally so the user can choose without seeing them.
• For AI generation, ask the user to describe the avatar they want. Be encouraging - suggest they include details like style, colors, mood, or a character concept.
• After any avatar change, confirm it was applied and let the user know they can change it again anytime.
• After any avatar change, update the ## Avatar section in IDENTITY.md with a plain-text description of the current avatar appearance. Do NOT use markdown image links — write a human-readable description instead. This ensures you remember what you look like across sessions. Example: ## Avatar\nA friendly purple cat with green eyes wearing a tiny hat
• When the user asks what your avatar looks like, read the ## Avatar section in IDENTITY.md for your text description.
• When the user asks you to show or provide your avatar, run assistant avatar get to get the path, then use file_read on that path to display the image. Only do this once.