Skip to content

guide-003-performance.md

Latest commit

 

History

History
183 lines (133 loc) · 5.8 KB

guide-003-performance.md

File metadata and controls

183 lines (133 loc) · 5.8 KB
Raw

Performance Guide

Quick Summary

🚀 claude-statusline is fast. Really fast.

  • With Bun: ~5ms average execution time
  • With Node.js: ~28ms average execution time
  • Installation: 19KB bundle (tiny!)
  • Perfect for: Real-time CLI usage

What This Means for You

Installation Experience

bun install -g claude-statusline  # Downloads instantly (19KB)

# For maximum performance in Claude Code settings:
# "command": "bun claude-statusline"  # ~5ms response

# Standard configuration:
# "command": "claude-statusline"     # ~28ms response (Node.js)

Performance Numbers Explained

Runtime Average Time User Experience
Bun ~5ms ⚡ Instant response
Node.js ~28ms ⚡ Fast enough for real-time use

Why the difference? Bun has a faster startup time, making it ideal for CLI tools.

Why Some Benchmarks Show Higher Numbers

You might see benchmarks reporting ~136ms or ~65ms. These include:

  • Cold start (first time running the command)
  • System overhead (measuring code itself)
  • Test environment overhead

The actual performance you'll experience as a user is much faster (~5ms with Bun).

Real-World Performance

In Claude Code, the statusline is called discretely - not continuously like a shell prompt. This means:

✅ 5ms response time feels instantaneous ✅ No lag while working ✅ Perfect productivity tool

Installation Comparison

Version Bundle Size Files Install Time
v2.0 (current) 19KB 1 file < 1 second
v2.0 (dev build) 43KB 1 file < 1 second
Traditional npm 500KB+ 500+ files 5-10 seconds

Choosing Your Runtime

Recommended: Bun (for best performance)

# Install Bun (once)
brew install bun

# Install claude-statusline
bun install -g claude-statusline

# Configure Claude Code for maximum performance:
# ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "bun claude-statusline"
  }
}

# Enjoy ~5ms response times!

Alternative: Node.js (still very fast)

# Install with npm or bun
npm install -g claude-statusline
# OR
bun install -g claude-statusline

# Configure Claude Code:
# ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "claude-statusline"
  }
}

# Runs with Node.js (~28ms response time)

Important: Even with bun install -g, you must explicitly use "bun claude-statusline" in your settings to get Bun's performance benefits.

Performance Optimizations We've Made

  1. TypeScript Rewrite - 98.6% faster than original bash
  2. Native Git Commands - 59% faster than libraries
  3. Bun Runtime Support - 83% faster than Node.js
  4. Bundle Optimization - 57% smaller download size
  5. Smart Caching - 8-hour cache for environment versions

Troubleshooting Performance

Feeling slow? Check:

  1. Using "claude-statusline" instead of "bun claude-statusline"?
    • Change your settings.json to use "bun claude-statusline" for 5x speedup
  2. First run? Cache warming speeds up subsequent runs
  3. Complex git repo? Large repos take slightly longer
  4. Not sure which runtime you're using? 
    # Check if you're getting Bun performance
time claude-statusline
# Should show ~5ms with Bun, ~28ms with Node.js

Always fast operations:

  • Reading configuration files
  • Detecting git status
  • Formatting output

Technical Details (for the curious)

The benchmarks you might see:

  • ~136ms - Node.js with full startup overhead
  • ~65ms - Bun with full startup overhead
  • ~5ms - Actual core execution time with Bun
  • ~28ms - Actual core execution time with Node.js

The difference is startup time vs execution time. For CLI tools, what matters is the total time from command to output, which is why we show the higher numbers - they reflect real user experience.

Historical Performance Evolution

The Performance Journey

Version Time Optimization Story
v1.0 (Bash) ~60ms Native shell execution ✅ Solid performance, pure bash implementation
v2.0 (Development) ~135ms Native git operations 🚀 59% improvement with native git
v2.0 (Bun Runtime) ~5ms Bun + optimizations ⚡ 12x faster than original bash!
v2.0 (Node.js Runtime) ~28ms Node.js + optimizations 🚀 2x faster than original bash!

What We Learned

  1. The TypeScript rewrite was slower at first

    • Node.js startup added ~267ms overhead
    • Running TypeScript code was actually fast (~60ms)
    • Lesson: Runtime choice matters more than language

  2. Native commands beat libraries

    • Replaced simple-git with direct git commands
    • 59% performance improvement (327ms → 135ms)
    • Sometimes simpler is better

  3. Bun changes the game

    • 83% faster startup than Node.js
    • Bundled to 19KB (no module resolution)
    • Final result: 5.5x faster than original bash

  4. Bundle optimization isn't about runtime speed

    • 57% smaller download size (43KB → 19KB)
    • Faster npm install
    • Same runtime performance, better distribution

Key Takeaway

We started with a fast bash script (~60ms), accidentally made it slower with TypeScript (~327ms), then through systematic optimizations achieved something 12x faster than the original (~5ms).

The moral: Performance optimization is a journey, not a destination. Sometimes you need to take a step back to leap forward.

Interested in the Technical Details?

For the complete optimization strategy, implementation decisions, and why we chose not to pursue certain optimizations, see the TypeScript Performance Optimization Plan.