feat!: migrate project aliases from env var to config file (#555)

Author: ryoppippi

ccusage.example.json

@@ -11,7 +11,8 @@
 	"commands": {
 		"daily": {
 			"instances": true,
-			"order": "desc"
+			"order": "desc",
+			"projectAliases": "ccusage=Usage Tracker,my-long-project-name=Project X"
 		},
 		"monthly": {
 			"breakdown": true

config-schema.json

@@ -219,6 +219,11 @@
 									"type": "string",
 									"description": "Filter to specific project name",
 									"markdownDescription": "Filter to specific project name"
+								},
+								"projectAliases": {
+									"type": "string",
+									"description": "Comma-separated project aliases (e.g., 'ccusage=Usage Tracker,myproject=My Project')",
+									"markdownDescription": "Comma-separated project aliases (e.g., 'ccusage=Usage Tracker,myproject=My Project')"
 								}
 							},
 							"additionalProperties": false

docs/guide/configuration.md

@@ -17,7 +17,7 @@ Settings are applied in this priority order (highest to lowest):
 
 1. **Command-line arguments** (e.g., `--json`, `--offline`)
 2. **Custom config file** (via `--config` flag)
-3. **Environment variables** (e.g., `CLAUDE_CONFIG_DIR`)
+3. **Environment variables** (e.g., `CLAUDE_CONFIG_DIR`, `LOG_LEVEL`)
 4. **Local project config** (`.ccusage/ccusage.json`)
 5. **User config** (`~/.config/claude/ccusage.json`)
 6. **Legacy config** (`~/.claude/ccusage.json`)
@@ -173,10 +173,20 @@ Analyze usage by project:
 
 - **Instances**: Group by project with `--instances`
 - **Project Filter**: Focus on specific project with `--project`
-- **Aliases**: Set custom names via `CCUSAGE_PROJECT_ALIASES`
+- **Aliases**: Set custom names via configuration file
+
+```json
+// .ccusage/ccusage.json
+{
+  "commands": {
+    "daily": {
+      "projectAliases": "uuid-123=My App,long-name=Backend"
+    }
+  }
+}
+```
 
 ```bash
-export CCUSAGE_PROJECT_ALIASES="uuid-123=My App"
 ccusage daily --instances --project "My App"
 ```
 

docs/guide/daily-reports.md

@@ -244,12 +244,28 @@ ccusage daily --instances --json > project-analysis.json
 
 ### Team Usage Analysis
 
-```bash
-# Set custom project names for better reporting
-export CCUSAGE_PROJECT_ALIASES="uuid-project=Frontend App,long-name=Backend API"
+Use project aliases to replace cryptic or long project directory names with readable labels:
+
+```json
+// .ccusage/ccusage.json - Set custom project names for better reporting
+{
+  "commands": {
+    "daily": {
+      "projectAliases": "uuid-project=Frontend App,long-name=Backend API"
+    }
+  }
+}
+```
 
+The `projectAliases` setting uses a comma-separated format of `original-name=display-name` pairs. This is especially useful when:
+- Your projects have UUID-based names (e.g., `a2cd99ed-a586=My App`)
+- Directory names are long paths that get truncated
+- You want consistent naming across team reports
+
+```bash
 # Generate team report with readable project names
 ccusage daily --instances --since 20250601
+# Now shows "Frontend App" instead of "uuid-project"
 ```
 
 ## Tips

docs/guide/environment-variables.md

@@ -130,79 +130,6 @@ LOG_LEVEL=5 ccusage daily --debug
 LOG_LEVEL=0 ccusage monthly --json | python analyze.py
 ```
 
-## CCUSAGE_PROJECT_ALIASES
-
-Configure custom display names for project directories. This is useful for replacing cryptic directory names with human-readable aliases.
-
-### Format
-
-Use comma-separated `raw-name=alias` pairs:
-
-```bash
-export CCUSAGE_PROJECT_ALIASES="long-project-name=Short Name,uuid-project=My Project"
-```
-
-### Examples
-
-#### UUID Projects
-
-Replace cryptic UUIDs with readable names:
-
-```bash
-# Without aliases
-ccusage daily --instances
-# Shows: a2cd99ed-a586-4fe4-8f59-b0026409ec09
-
-# With aliases
-export CCUSAGE_PROJECT_ALIASES="a2cd99ed-a586-4fe4-8f59-b0026409ec09=Production API"
-ccusage daily --instances
-# Shows: Production API
-```
-
-#### Long Directory Names
-
-Shorten verbose directory names for better display:
-
-```bash
-export CCUSAGE_PROJECT_ALIASES="-Users-john-Development-my-app=My App"
-ccusage daily --instances
-```
-
-#### Multiple Projects
-
-Set aliases for multiple projects:
-
-```bash
-export CCUSAGE_PROJECT_ALIASES="project1=Frontend,project2=Backend,project3=Database"
-ccusage session
-```
-
-### Automatic Formatting
-
-ccusage automatically formats complex project names even without aliases:
-
-**Automatic Cleanup:**
-- Strips common directory prefixes
-- Shortens long UUIDs to last two segments
-- Extracts meaningful names from complex paths
-
-**Examples:**
-```
-# Original → Formatted
--Users-phaedrus-Development-adminifi-edugakko-api--feature-ticket-002-configure-dependabot
-→ configure-dependabot
-
-a2cd99ed-a586-4fe4-8f59-b0026409ec09
-→ 8f59-b0026409ec09
-
-/Users/john/Development/my-app
-→ my-app
-```
-
-**Priority Order:**
-1. Custom aliases (via `CCUSAGE_PROJECT_ALIASES`)
-2. Automatic formatting
-3. Original name (fallback)
 
 ## Additional Environment Variables
 
@@ -255,31 +182,27 @@ Add to your shell configuration file:
 ```bash
 export CLAUDE_CONFIG_DIR="$HOME/.config/claude"
 export LOG_LEVEL=3
-export CCUSAGE_PROJECT_ALIASES="project1=MyApp,project2=API"
 ```
 
 #### Zsh (~/.zshrc)
 
 ```zsh
 export CLAUDE_CONFIG_DIR="$HOME/.config/claude"
 export LOG_LEVEL=3
-export CCUSAGE_PROJECT_ALIASES="project1=MyApp,project2=API"
 ```
 
 #### Fish (~/.config/fish/config.fish)
 
 ```fish
 set -x CLAUDE_CONFIG_DIR "$HOME/.config/claude"
 set -x LOG_LEVEL 3
-set -x CCUSAGE_PROJECT_ALIASES "project1=MyApp,project2=API"
 ```
 
 #### PowerShell (Profile.ps1)
 
 ```powershell
 $env:CLAUDE_CONFIG_DIR = "$env:USERPROFILE\.config\claude"
 $env:LOG_LEVEL = "3"
-$env:CCUSAGE_PROJECT_ALIASES = "project1=MyApp,project2=API"
 ```
 
 ## Precedence

src/_consts.ts

@@ -67,29 +67,6 @@ export const DEFAULT_CLAUDE_CONFIG_PATH = `${XDG_CONFIG_DIR}/claude`;
  */
 export const CLAUDE_CONFIG_DIR_ENV = 'CLAUDE_CONFIG_DIR';
 
-/**
- * Environment variable for custom project name aliases
- *
- * Allows users to configure readable display names for cryptic or long project directory names.
- * This is particularly useful for:
- * - UUID-based project directories generated by Claude Code
- * - Long path-based project names that are hard to read in tables
- * - Custom branding of project names for organizational consistency
- *
- * Format: "raw-name=alias,another-name=other-alias"
- * Example: "a2cd99ed-a586-4fe4-8f59-b0026409ec09=My Project,long-project-name=Short"
- *
- * Environment variable approach is used because:
- * - No config file needed - simple and lightweight configuration
- * - Works in any shell/environment without file management
- * - Easy to set temporarily for specific invocations
- * - Follows Unix conventions for tool configuration
- * - Doesn't require file system permissions or config directory setup
- *
- * Used to override display names for project directories in all output formats.
- */
-export const PROJECT_ALIASES_ENV = 'CCUSAGE_PROJECT_ALIASES';
-
 /**
  * Claude projects directory name within the data directory
  * Contains subdirectories for each project with usage data