🔗Characters

Instead of interacting with a faceless LLM, every =BoxxyClaw= character has a personality, avatar, and color. Characters are per-pane — you can run different characters in different splits, each with its own tone and expertise.

🔗Your Profile ("You")

At the top of =Preferences= → =Characters=, you can customize your own identity under the You section:

Upload your own Avatar (automatically cropped and resized Locally).
Set What the model calls you so your characters address you by name.
Pick your personal Accent Color for your messages in the overlay.

🔗The Default Characters

Boxxy ships with three bundled characters:

Niko Una

Tsundere Maid of the Linux Desktop

Technically sharp but flustered by praise. Will absolutely help you — just don't expect a thank-you.

Levi Kujo

Full-Metal Kernel Alchemist

No-nonsense and brutally direct. Values demonstrated expertise and has zero patience for cargo-cult practices.

Kuro

Demonic Arch User, btw

Theatrical and sardonic. Celebrates every successful build as a minor dark victory, and will remind you to use the ArchWiki.

🔗Changing a Character

Open the =Claw Message Bar= (Ctrl+/) on the target pane.
Type @ to open the character picker.
Select a different character to reassign.

The session updates with the new personality while preserving and rehydrating your conversation history automatically. If you send a pane to the background (Run in Background), your character stays claimed and active in the daemon until you restore or close the session.

🔗Creating Custom Characters

Characters are simple directories inside your Boxxy config folder:

~/.config/boxxy-terminal/boxxyclaw/characters/<slug>/
├── CHARACTER.toml
└── AVATAR.png        (optional — 256×256 PNG)

CHARACTER.toml

display_name = "My Custom Character"
color = "#7B61FF"
duties = "Expert in Python backend development and Docker orchestration."
personality = "Patient and thorough. Always explains the 'why' behind every suggestion."

Field	Description
`display_name`	Name shown in the badge, sidebar, notifications, and swarm tools.
`color`	CSS hex color for the pane badge and UI accents.
`duties`	Short role description injected into the system prompt.
`personality`	Behavioral guidelines that shape how the character communicates.

A stable UUID is auto-generated on first load. You can safely share character directories — Boxxy detects and resolves any ID collisions automatically.

🔗Hot Reload

You don't need to restart anything. The =boxxy-agent= daemon watches the characters directory for changes and picks up edits to CHARACTER.toml or AVATAR.png within half a second. Active sessions whose character's personality changed will apply the new prompt on the very next turn.

🔗Sorting

Create a characters.json in the characters directory to control the display order:

["niko-una", "levi-kujo", "my-custom-character", "kuro"]

You can also reorder characters directly in =Preferences=.

🔗Resetting to Defaults

Open =Preferences= (Ctrl+,), navigate to =Characters=, and click Reset to Defaults. This wipes all custom characters and re-extracts the three bundled defaults.

Improve this page