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
Fromsrc/utils/installer.ts:13-16:
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 theinit process, you’ll be prompted:
src/cli/prompts.ts:54-62:
How Settings Are Applied
Claude Code follows a precedence order when loading settings:Project-Level Settings
./.claude/settings.json is checked first.If a statusLine configuration exists, it takes highest priority.Global Settings
~/.claude/settings.json is used as fallback.Only applied if no project-level statusLine is configured.Safety Features
Overwrite Protection
Fromsrc/utils/installer.ts:22-35, cc-statusline never overwrites without confirmation:
Settings Protection
Fromsrc/utils/installer.ts:72-90, existing settings.json configurations are protected:
Comparison Table
| Feature | Global Installation | Project Installation |
|---|---|---|
| Location | ~/.claude/ | ./.claude/ |
| Scope | All projects | Single project |
| Priority | Lower | Higher |
| Version Control | Not recommended | Recommended |
| Team Collaboration | Personal only | Shareable |
| Default | No | Yes |
| Safety | Affects all projects | Isolated |
Common Scenarios
Scenario 1: Individual Developer
Goal: Same statusline everywhere for consistency. Recommendation: Global installationScenario 2: Team Project
Goal: Share statusline configuration with team via git. Recommendation: Project installation + commit to version controlScenario 3: Mixed Usage
Goal: Global default with project overrides. Strategy:Scenario 4: Multiple Personalities
Goal: Different statuslines for work vs personal projects. Strategy: Use project installation for all, no globalMigration Between Types
Global to Project
To migrate from global to project installation:Project to Global
To migrate from project to global:Platform Differences
Windows
Fromsrc/utils/installer.ts:94-96, Windows requires explicit bash command:
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 WindowsTroubleshooting
Global Installation Not Working
Symptom: Statusline doesn’t appear in any project Solution:-
Verify global settings exist:
-
Check for project-level override:
-
Remove project override if needed:
Project Installation Not Overriding
Symptom: Global statusline appears instead of project one Solution:-
Verify project settings.json exists:
-
Check statusLine configuration:
-
Ensure the command path is correct:
Permission Issues with Global
Symptom:Permission denied when running global statusline
Solution:
Best Practices
Use Project Installation by Default
Use Project Installation by Default
Start with project installation for safety and flexibility.You can always switch to global later if you find it suits your workflow.
Commit to Version Control
Commit to Version Control
When using project installation, commit both files:This ensures team members have the same statusline experience.
Document Team Conventions
Document Team Conventions
If using project installation in a team, document in your README:
Keep Global Minimal
Keep Global Minimal
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