Skip to main content

Overview

Starting with v1.2.4, cc-statusline supports two installation modes:
  • 🏠 Global Installation (~/.claude/) - Use the same statusline across all projects
  • 📂 Project Installation (./.claude/) - Keep statusline settings project-specific
Project installation is the default and recommended option for most users

Installation Locations

From src/utils/installer.ts:13-16:
const isGlobal = config.installLocation === 'global'
const claudeDir = isGlobal 
  ? path.join(os.homedir(), '.claude') 
  : './.claude'
const scriptPath = path.join(claudeDir, 'statusline.sh')

Global Installation

Location: ~/.claude/statusline.sh Settings: ~/.claude/settings.json When to use:
  • You want the same statusline across all projects
  • You work on many small projects and don’t want to configure each one
  • You prefer a single source of truth for your statusline configuration

Project Installation

Location: ./.claude/statusline.sh Settings: ./.claude/settings.json When to use:
  • Different projects have different statusline needs
  • You want to commit statusline configuration to version control
  • You’re working in a team and want consistent statusline settings
  • You value safety and isolation (default behavior)

Choosing Installation Type

During the init process, you’ll be prompted:
📍 Where would you like to install the statusline?
  🏠 Global (~/.claude) - Use across all projects
❯ 📂 Project (./.claude) - Only for this project
From src/cli/prompts.ts:54-62:
{
  type: 'list',
  name: 'installLocation',
  message: '📍 Where would you like to install the statusline?',
  choices: [
    { name: '🏠 Global (~/.claude) - Use across all projects', value: 'global' },
    { name: '📂 Project (./.claude) - Only for this project', value: 'project' }
  ],
  default: 'project'
}

How Settings Are Applied

Claude Code follows a precedence order when loading settings:
1

Project-Level Settings

./.claude/settings.json is checked first.If a statusLine configuration exists, it takes highest priority.
2

Global Settings

~/.claude/settings.json is used as fallback.Only applied if no project-level statusLine is configured.
3

Default Settings

Claude Code’s built-in defaults.Used when no custom statusLine configuration exists.
You can override a global statusline by installing a project-level one

Safety Features

Overwrite Protection

From src/utils/installer.ts:22-35, cc-statusline never overwrites without confirmation:
try {
  await fs.access(scriptPath)
  // File exists, ask for confirmation
  const { confirmOverwrite } = await inquirer.prompt([{
    type: 'confirm',
    name: 'confirmOverwrite',
    message: `⚠️  ${isGlobal ? 'Global' : 'Project'} statusline.sh already exists. Overwrite?`,
    default: false
  }])
  shouldWrite = confirmOverwrite
} catch {
  // File doesn't exist, proceed
}
If you decline to overwrite, the installation is cancelled and your existing configuration is preserved

Settings Protection

From src/utils/installer.ts:72-90, existing settings.json configurations are protected:
if (existingStatusLine && existingStatusLine.command) {
  const isOurStatusline = existingStatusLine.command?.includes('statusline.sh')
  
  if (!isOurStatusline) {
    // There's a different statusline configured, ask user
    const { confirmReplace } = await inquirer.prompt([{
      type: 'confirm',
      name: 'confirmReplace',
      message: `⚠️  ${isGlobal ? 'Global' : 'Project'} settings.json already has a statusLine configured (${existingStatusLine.command}). Replace it?`,
      default: false
    }])
    
    if (!confirmReplace) {
      console.warn('⚠️  Statusline script was saved but settings.json was not updated.')
      return
    }
  }
}

Comparison Table

FeatureGlobal InstallationProject Installation
Location~/.claude/./.claude/
ScopeAll projectsSingle project
PriorityLowerHigher
Version ControlNot recommendedRecommended
Team CollaborationPersonal onlyShareable
DefaultNoYes
SafetyAffects all projectsIsolated

Common Scenarios

Scenario 1: Individual Developer

Goal: Same statusline everywhere for consistency. Recommendation: Global installation
cd ~
cc-statusline init
# Select: 🏠 Global (~/.claude) - Use across all projects
Install from your home directory to avoid accidentally creating project files

Scenario 2: Team Project

Goal: Share statusline configuration with team via git. Recommendation: Project installation + commit to version control
cd /path/to/project
cc-statusline init
# Select: 📂 Project (./.claude) - Only for this project

git add .claude/statusline.sh .claude/settings.json
git commit -m "Add team statusline configuration"

Scenario 3: Mixed Usage

Goal: Global default with project overrides. Strategy:
1

Install globally

cd ~
cc-statusline init
# Select: Global
# Enable all features you usually want
2

Override in specific projects

cd /path/to/special-project
cc-statusline init  
# Select: Project
# Use minimal features for performance

Scenario 4: Multiple Personalities

Goal: Different statuslines for work vs personal projects. Strategy: Use project installation for all, no global
# Work project
cd ~/work/client-project
cc-statusline init
# Select: Project
# Enable: directory, git, model, context only

# Personal project  
cd ~/personal/side-project
cc-statusline init
# Select: Project
# Enable: all features including costs

Migration Between Types

Global to Project

To migrate from global to project installation:
1

Copy global statusline

mkdir -p .claude
cp ~/.claude/statusline.sh .claude/
2

Update settings.json

Create .claude/settings.json:
{
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}
3

Restart Claude Code

Project settings now take precedence

Project to Global

To migrate from project to global:
1

Copy project statusline

mkdir -p ~/.claude
cp .claude/statusline.sh ~/.claude/
2

Update global settings

Edit ~/.claude/settings.json:
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}
3

Remove project configuration

rm .claude/statusline.sh
# Optionally remove statusLine from .claude/settings.json
4

Restart Claude Code

Global settings now apply

Platform Differences

Windows

From src/utils/installer.ts:94-96, Windows requires explicit bash command:
const commandPath = process.platform === 'win32'
  ? `bash ${isGlobal ? '.claude' : '.claude'}/${scriptName}`
  : (isGlobal ? `~/.claude/${scriptName}` : `.claude/${scriptName}`)
Global on Windows: bash .claude/statusline.sh Project on Windows: bash .claude/statusline.sh

macOS & Linux

Global: ~/.claude/statusline.sh Project: .claude/statusline.sh
The ~ home directory abbreviation works on macOS and Linux but not Windows

Troubleshooting

Global Installation Not Working

Symptom: Statusline doesn’t appear in any project Solution:
  1. Verify global settings exist:
    cat ~/.claude/settings.json
    
  2. Check for project-level override:
    cat .claude/settings.json 2>/dev/null
    
  3. Remove project override if needed:
    # Edit .claude/settings.json and remove statusLine section
    

Project Installation Not Overriding

Symptom: Global statusline appears instead of project one Solution:
  1. Verify project settings.json exists:
    ls -la .claude/settings.json
    
  2. Check statusLine configuration:
    cat .claude/settings.json
    
  3. Ensure the command path is correct:
    {
      "statusLine": {
        "type": "command",
        "command": ".claude/statusline.sh",
        "padding": 0
      }
    }
    

Permission Issues with Global

Symptom: Permission denied when running global statusline Solution:
chmod +x ~/.claude/statusline.sh

Best Practices

Start with project installation for safety and flexibility.You can always switch to global later if you find it suits your workflow.
When using project installation, commit both files:
git add .claude/statusline.sh .claude/settings.json
This ensures team members have the same statusline experience.
If using project installation in a team, document in your README:
## Statusline

This project uses cc-statusline. Run `cc-statusline preview .claude/statusline.sh`
to see the current configuration.
If you use global installation, keep it minimal and fast.Disable expensive features like ccusage integration that might slow down all projects.

Next Steps

Configuration Guide

Customize your statusline features

Troubleshooting

Fix installation issues

Build docs developers (and LLMs) love