Skip to main content

​
Overview

Themes control the visual density, layout, and information presentation of your statusline. Currently, cc-statusline supports three theme modes: minimal, detailed, and compact.

​
Theme Configuration

Themes are defined in the StatuslineConfig interface (prompts.ts:7): 
theme: 'minimal' | 'detailed' | 'compact'
Default: 'detailed' (hardcoded in prompts.ts:73) Note: Theme selection is not currently exposed in the interactive prompts. The theme is automatically set to detailed during configuration.

​
Available Themes

​
Detailed Theme (Default)

​
detailed
theme
default:"true"
Layout: Full 3-line layout with all information and progress barsFeatures:
  • Complete information display
  • Progress bars for context and session
  • Color-coded sections
  • Emoji indicators
Example Output:
📁 ~/Projects/cc-statusline  🌿 main  🤖 Sonnet 4  📟 v1.0.85  🎨 default
🧠 Context Remaining: 83% [========--]  ⌛ 3h 7m until reset at 01:00 (37%) [===-------]
💰 $49.00 ($16.55/h)  📊 14638846 tok (279900 tpm)
Use Case: Maximum information density with visual aidsPerformance: ~45-80ms execution time

​
Minimal Theme

​
minimal
theme
Layout: Reduced visual elements, no progress barsFeatures:
  • Text-only percentages and values
  • No progress bars (bash-generator.ts:23)
  • Color support if enabled
  • Emoji indicators
Differences from Detailed:
  • Session progress bar hidden: showProgressBar: config.theme !== 'minimal'
  • More compact vertical space
Example Output:
📁 ~/my-app  🌿 main  🤖 Claude Sonnet  📟 v1.0.85
🧠 Context Remaining: 95%
💰 $2.48 ($12.50/h)
Use Case: Clean, distraction-free display with essential informationPerformance: Slightly faster than detailed (~40-70ms)

​
Compact Theme

​
compact
theme
Layout: Condensed git informationFeatures:
  • Same overall layout as detailed
  • Compact git display mode (bash-generator.ts:31)
  • All other features identical to detailed
Git Differences:
const gitConfig = {
  enabled: hasGit,
  showBranch: hasGit,
  showChanges: false,
  compactMode: config.theme === 'compact' // Only affects git
}
Use Case: When git information should be more conciseNote: As of v1.4.0, delta changes are disabled for all themes, so compact mode has minimal visible difference.

​
Theme Implementation

Themes are applied during bash script generation in bash-generator.ts:9-62: 
export function generateBashStatusline(config: StatuslineConfig): string {
  // Build usage feature config
  const usageConfig = {
    enabled: hasUsage && config.ccusageIntegration,
    showCost: config.features.includes('usage'),
    showTokens: config.features.includes('tokens'),
    showBurnRate: config.features.includes('burnrate'),
    showSession: config.features.includes('session'),
    showProgressBar: config.theme !== 'minimal' && config.features.includes('session')
  }

  // Build git feature config
  const gitConfig = {
    enabled: hasGit,
    showBranch: hasGit,
    showChanges: false,
    compactMode: config.theme === 'compact'
  }
}

​
Theme Effects by Feature

​
Progress Bars

Minimal theme disables session progress bars: 
showProgressBar: config.theme !== 'minimal' && config.features.includes('session')
  • Detailed: [========--] shown for session and context
  • Compact: [========--] shown for session and context
  • Minimal: No session progress bar, percentage only

​
Git Display

Compact theme enables condensed git mode: 
compactMode: config.theme === 'compact'
This is passed to generateGitBashCode() in the git feature module.

​
Color Support

All themes support colors when colors: true is configured: 
${generateColorBashCode({ enabled: config.colors, theme: config.theme })}
${config.colors ? generateBasicColors() : ''}
Color application is independent of theme choice.

​
Theme Metadata

The selected theme is embedded in the generated script header (bash-generator.ts:37): 
# Generated by cc-statusline v1.4.0
# Custom Claude Code statusline - Created: 2026-03-04T10:30:00.000Z
# Theme: detailed | Colors: true | Features: directory, git, model, context

​
Changing Themes

Currently, themes cannot be selected during interactive setup. To use a different theme: Option 1: Modify the default in source code 
// src/cli/prompts.ts:73
theme: 'minimal', // Change from 'detailed'
Option 2: Use programmatic configuration (if exposing custom config in future) Future Enhancement: Theme selection may be added to the interactive prompts in a future version.

​
Performance Comparison

ThemeAvg ExecutionMemoryFeatures
Detailed45-80ms~2MBFull info + progress bars
Minimal40-70ms~2MBText only, no progress bars
Compact45-80ms~2MBCondensed git display
Note: Performance differences are minimal. Theme choice should be based on visual preference.

​
Color Themes

The theme parameter is also passed to generateColorBashCode() (bash-generator.ts:49): 
${generateColorBashCode({ enabled: config.colors, theme: config.theme })}
This allows color palettes to potentially vary by theme, though current implementation uses consistent colors across all themes.

​
Layout Structure

All themes follow the same 3-line structure (from bash-generator.ts:214-293): Line 1: Core information 
printf '📁 %s%s%s' "$(dir_color)" "$current_dir" "$(rst)"
printf '  🌿 %s%s%s' "$(git_color)" "$git_branch" "$(rst)"
printf '  🤖 %s%s%s' "$(model_color)" "$model_name" "$(rst)"
Line 2: Context and session 
line2="🧠 $(context_color)Context Remaining: ${context_pct} [${context_bar}]$(rst)"
line2="$line2  ⌛ $(session_color)${session_txt}$(rst) $(session_color)[${session_bar}]$(rst)"
Line 3: Usage analytics 
line3="💰 $(cost_color)\$(printf '%.2f' "$cost_usd")$(rst) ($(burn_color)\$${cost_per_hour_formatted}/h$(rst))"
line3="$line3  📊 $(usage_color)${tot_tokens} tok (${tpm_formatted} tpm)$(rst)"
Themes modify what’s displayed within this structure, not the structure itself.

Build docs developers (and LLMs) love

Get started for freeTalk to us