Kodi Companion

Kodi is an AI-powered companion character that lives in the KCode terminal UI. It reacts to your coding session in real-time with contextual animations and LLM-generated commentary.

What is Kodi?

Kodi is a small ASCII character displayed above the input prompt. It shows:

Session info: model name, permission mode, working directory, elapsed time
Live metrics: token count, tool usage, running agents, context window usage
Mood-based sprites: 9 moods with animated variants (idle, happy, excited, thinking, working, worried, sleeping, celebrating, curious)
Contextual reactions: LLM-generated responses to session events

 ╭──────────────────────────────────────────────────────────────╮
 │  ╭───╮    KCode v1.0.0 — Kulvex Code by Astrolexis          │
 │  │^ ◡^│   mnemo:mark5-80b • auto • ~/my-project             │
 │  ╰─┬─╯    tok:12,450 • tools:23 • 8m                        │
 │   /|\     💬 Nice refactor! Clean and DRY.                   │
 │   / \                                                        │
 ╰──────────────────────────────────────────────────────────────╯
 mnemo:mark5-80b ~/my-project >

How Reactions Work

Kodi reacts to session events:

Event	Trigger	Example Mood
Tool starts	KCode runs a tool (Bash, Edit, etc.)	working
Tool completes	Tool finishes successfully	happy
Tool errors	Tool fails or returns an error	worried
Thinking	Model is generating a response	thinking
Streaming	Tokens are being streamed	curious
Turn ends	Model finishes responding	idle
Compaction	Context window is being compacted	thinking
Agent spawn	A subagent is launched	excited
Long idle (30s+)	No activity for 30 seconds	sleeping

LLM-Generated Reactions

Kodi uses the local LLM to generate unique, contextual reactions. A hardcoded fallback is shown instantly while the LLM generates a creative response in the background. There’s a 5-second cooldown between LLM calls to avoid overloading.

If the LLM is unavailable, Kodi falls back to built-in reactions.

Moods & Sprites

Kodi has 9 moods, each with multiple sprite variants that animate:

Mood	When
`idle`	Waiting for input
`happy`	Task completed, test passed
`excited`	Milestone reached, agent spawned
`thinking`	Model generating response
`working`	Tool executing
`worried`	Error occurred, tool failed
`sleeping`	Idle for 2+ minutes
`celebrating`	Major milestone (100 tools, etc.)
`curious`	Streaming, exploring code

Milestones

Kodi reacts to session milestones:

10 tools used — “Getting warmed up!”
50 tools used — “Halfway to mastery!”
100 tools used — “Century! Let’s celebrate!”
50K tokens — Context growing
100K tokens — Large session alert

Configuration

Kodi is enabled by default. It appears above the input prompt in interactive mode and adapts to your terminal width.

Kodi does not appear in:

--print mode (non-interactive)
Piped output
Single-shot mode without TUI

Installation Models