tangent

Tangent

Terminal avatars for AI agents. Go library.

v0.2.0: Now with Frame Cache API (500x faster) and plug-and-play Bubble Tea integration. No more custom adapters needed.

Features

• 7 characters × 16 animated states × 4 color themes = 448 combinations
• Frame Cache API - Pre-rendered frames for O(1) access (500x faster)
• Bubble Tea Component - Built-in AnimatedCharacter (5 lines vs 310-line adapter)
• Code Generation - Character management from single source of truth
• Theme System - Global color themes (latte, bright, garden, cozy)

Install

go get github.com/wildreason/tangent/pkg/characters

What's New in v0.2.0

Frame Cache API - 500x Faster Performance

Pre-rendered, pre-colored frames eliminate repeated compilation:

agent, _ := characters.LibraryAgent("sam")
cache := agent.GetFrameCache()

// O(1) access - frames already compiled and colored
frames := cache.GetStateFrames("plan")  // [][]string

Performance: 50µs → 0.1µs per frame (500x speedup)

Bubble Tea Integration - No Adapter Needed

Built-in component eliminates 310-line custom adapters:

import "github.com/wildreason/tangent/pkg/characters/bubbletea"

agent, _ := characters.LibraryAgent("sam")
char := bubbletea.NewAnimatedCharacter(agent, 100*time.Millisecond)
char.SetState("plan")

program := tea.NewProgram(char)
program.Run()

Code Reduction: 310 lines → 5 lines (98% reduction)

Code Generation - Easy Character Management

Rename or add characters by editing one file:

# Edit constants.go
vim pkg/characters/library/constants.go

# Regenerate all files
make generate

# Test
make test

See CHANGELOG.md for full v0.2.0 details.

Usage

import "github.com/wildreason/tangent/pkg/characters"

agent, _ := characters.LibraryAgent("sam")
agent.Plan(os.Stdout)
agent.Think(os.Stdout)
agent.Execute(os.Stdout)

API

// Get agent
agent, err := characters.LibraryAgent(name)

// State methods
agent.Plan(writer)
agent.Think(writer)
agent.Execute(writer)
agent.Wait(writer)
agent.Error(writer)

// Custom states
agent.ShowState(writer, "arise")
agent.ShowState(writer, "approval")

// Introspection
states := agent.ListStates()
hasState := agent.HasState("think")

// Themes - set color theme for all agents
characters.SetTheme("latte")        // Switch to latte theme
themes := characters.ListThemes()   // ["bright", "cozy", "garden", "latte"]
current := characters.GetCurrentTheme()  // "latte"

// Frame Cache API - pre-rendered frames for performance
cache := agent.GetFrameCache()
baseLines := cache.GetBaseFrame()      // []string (pre-colored)
planFrames := cache.GetStateFrames("plan")  // [][]string (pre-colored)

TUI Framework Integration

Bubble Tea (Plug-and-Play)

import (
    tea "github.com/charmbracelet/bubbletea"
    "github.com/wildreason/tangent/pkg/characters"
    "github.com/wildreason/tangent/pkg/characters/bubbletea"
)

// Load character
agent, _ := characters.LibraryAgent("sam")

// Create animated component
char := bubbletea.NewAnimatedCharacter(agent, 100*time.Millisecond)
char.SetState("plan")

// Run in Bubble Tea
program := tea.NewProgram(char)
program.Run()

See examples/bubbletea_demo for full demo.

Custom TUI Frameworks (tview, etc.)

// Use Frame Cache for O(1) frame access
cache := agent.GetFrameCache()
frames := cache.GetStateFrames("think")
// frames[i] is []string (pre-colored, ready to render)

Avatars

7 characters × 16 states × 4 themes

States

arise, wait, think, plan, execute, error, read, search, write, bash, build, communicate, block, blocked, resting, approval

Character Management

Characters are auto-generated from pkg/characters/library/constants.go.

Renaming a Character

# 1. Edit constants.go
vim pkg/characters/library/constants.go
# Change: CharacterGa = "ga" → CharacterGa = "gabe"

# 2. Regenerate
make generate

# 3. Test and commit
make test
git add .
git commit -m "Rename ga to gabe"

All character files and theme mappings are updated automatically.

Adding a Character

1. Add character constants to constants.go:
   • Name constant (e.g., CharacterNew = "newchar")
   • Color constant (e.g., ColorNew = "#ABCDEF")
   • Theme colors for all 4 themes
2. Run make generate
3. New character file created automatically

See CODEGEN.md for details.

Documentation

• API Reference - Complete API documentation
• Ecosystem Guide - TUI framework integration
• Code Generation - Character management
• CHANGELOG - Version history

Examples

• Bubble Tea Demo - Interactive animated demo

Version

Current: v0.2.0-alpha (2025-11-25)

• v0.2.0-alpha: Frame Cache API + Bubble Tea + Code Generation
• v0.1.1: Character name updates (sam, rio)
• v0.1.0: Initial stable release

License

MIT © 2025 Wildreason, Inc