feat: adding configurable token limits

config-schema.json

@@ -655,14 +655,20 @@
 								},
 								"tokenLimit": {
 									"type": "string",
-									"description": "Token limit for quota warnings (e.g., 500000 or \"max\")",
-									"markdownDescription": "Token limit for quota warnings (e.g., 500000 or \"max\")"
+									"description": "Token limit for quota warnings (number: e.g. 50000, \"max\", \"avg\", or \"median\")",
+									"markdownDescription": "Token limit for quota warnings (number: e.g. 50000, \"max\", \"avg\", or \"median\")"
 								},
 								"sessionLength": {
 									"type": "number",
 									"description": "Session block duration in hours (default: 5)",
 									"markdownDescription": "Session block duration in hours (default: 5)",
 									"default": 5
+								},
+								"tokenLimitSessions": {
+									"type": "number",
+									"description": "Number of recent completed sessions to use for token limit calculation (default: 10)",
+									"markdownDescription": "Number of recent completed sessions to use for token limit calculation (default: 10)",
+									"default": 10
 								}
 							},
 							"additionalProperties": false

docs/guide/blocks-reports.md

@@ -83,16 +83,21 @@ Perfect for understanding recent usage patterns without scrolling through all hi
 
 ### Token Limit Tracking
 
-Set token limits to monitor quota usage:
+Set token limits to monitor quota usage with flexible calculation methods:
 
 ```bash
 # Set explicit token limit
 ccusage blocks --token-limit 500000
 
-# Use highest previous block as limit
-ccusage blocks --token-limit max
-# or short form:
+# Use automatic calculation methods
+ccusage blocks --token-limit max     # Highest previous block (default)
+ccusage blocks --token-limit avg     # Average of all blocks
+ccusage blocks --token-limit median  # Median of all blocks
+
+# Short forms
 ccusage blocks -t max
+ccusage blocks -t avg
+ccusage blocks -t median
 ```
 
 When limits are set, blocks display:
@@ -101,6 +106,149 @@ When limits are set, blocks display:
 - 🚨 **Alert indicators** when exceeding limits
 - **Progress bars** showing usage relative to limit
 
+#### Token Limit Calculation Methods
+
+Choose how automatic token limits are calculated from your usage history using the `--token-limit` option with method keywords:
+
+```bash
+# Maximum tokens from any block (default - conservative)
+ccusage blocks --token-limit max
+
+# Average tokens across all blocks (balanced)
+ccusage blocks --token-limit avg
+
+# Median tokens across all blocks (robust against outliers)
+ccusage blocks --token-limit median
+```
+
+#### Limiting Calculation to Recent Sessions
+
+Control how many recent blocks are used for automatic limit calculation:
+
+```bash
+# Use only the 10 most recent blocks (default)
+ccusage blocks --token-limit-sessions 10
+
+# Use only the 5 most recent blocks (more responsive to patterns)
+ccusage blocks --token-limit-sessions 5
+
+# Use only the last block
+ccusage blocks --token-limit-sessions 1
+```
+
+#### Advanced Token Limit Examples
+
+Combine calculation methods with session limits for precise control:
+
+```bash
+# Conservative: Maximum of last 5 blocks
+ccusage blocks --token-limit max --token-limit-sessions 5
+
+# Balanced: Average of last 10 blocks
+ccusage blocks --token-limit avg --token-limit-sessions 10
+
+# Robust: Median of last 15 blocks (ignores outliers)
+ccusage blocks --token-limit median --token-limit-sessions 15
+
+# Recent pattern focus: Average of last 3 blocks
+ccusage blocks --token-limit avg --token-limit-sessions 3
+```
+
+#### Understanding Calculation Methods
+
+**Maximum (max)** - Most conservative approach:
+```bash
+ccusage blocks --token-limit max --token-limit-sessions 10
+```
+- **Best for**: Cost control, avoiding budget overruns
+- **Behavior**: Uses your highest usage block as the limit
+- **Result**: Most restrictive warnings, earliest alerts
+- **Use when**: You want strict budget management
+
+**Average (avg)** - Balanced approach:
+```bash
+ccusage blocks --token-limit avg --token-limit-sessions 10
+```
+- **Best for**: Typical usage patterns, consistent workflows
+- **Behavior**: Uses your average block usage as the limit
+- **Result**: Moderate warnings based on normal usage
+- **Use when**: You have consistent usage patterns
+
+**Median (median)** - Robust against outliers:
+```bash
+ccusage blocks --token-limit median --token-limit-sessions 10
+```
+- **Best for**: Variable usage with occasional large sessions
+- **Behavior**: Ignores extreme high/low usage blocks
+- **Result**: Warnings based on typical (not average) usage
+- **Use when**: You have mixed session types or occasional spikes
+
+#### Practical Token Limit Scenarios
+
+**Scenario 1: New User Learning Patterns**
+```bash
+# Start conservative, adjust based on experience
+ccusage blocks --token-limit max --token-limit-sessions 3
+```
+- **Why**: Uses maximum of last 3 sessions for safety
+- **Benefit**: Prevents accidental overuse while learning
+- **Adjustment**: Switch to `avg` method once patterns emerge
+
+**Scenario 2: Consistent Daily Developer**
+```bash
+# Balanced approach based on typical usage
+ccusage blocks --token-limit avg --token-limit-sessions 10
+```
+- **Why**: Average of last 10 sessions reflects normal workflow
+- **Benefit**: Warnings at appropriate levels for usual work
+- **Adjustment**: Increase sessions count during routine changes
+
+**Scenario 3: Project-Based Usage (Variable Intensity)**
+```bash
+# Median handles both light and heavy project phases
+ccusage blocks --token-limit median --token-limit-sessions 15
+```
+- **Why**: Median ignores occasional large refactoring sessions
+- **Benefit**: Consistent warnings despite usage variability
+- **Adjustment**: Use `max` during intense project phases
+
+**Scenario 4: Budget-Conscious Team Lead**
+```bash
+# Conservative limits with recent pattern awareness
+ccusage blocks --token-limit max --token-limit-sessions 7
+```
+- **Why**: Maximum of last week prevents budget overruns
+- **Benefit**: Early warnings help maintain cost discipline
+- **Adjustment**: Combine with explicit limits during month-end
+
+**Scenario 5: Experimental Developer (High Variance)**
+```bash
+# Robust calculation ignoring outliers
+ccusage blocks --token-limit median --token-limit-sessions 20
+```
+- **Why**: Large sample size with outlier protection
+- **Benefit**: Stable warnings despite experimental sessions
+- **Adjustment**: Switch to `avg` during stable development phases
+
+#### Understanding Calculation Methods with Session Limits
+
+The unified `--token-limit` option supports flexible calculation methods:
+
+**Current Unified Approach**:
+```bash
+# Choose your calculation method with a single option
+ccusage blocks --token-limit avg --token-limit-sessions 10
+ccusage blocks --token-limit median --token-limit-sessions 15
+ccusage blocks --token-limit max --token-limit-sessions 5
+```
+
+**Key Benefits**:
+- **Better Accuracy**: Methods reflect actual usage patterns
+- **Outlier Handling**: Median method ignores extreme sessions
+- **Recent Focus**: Session limits consider recent workflow changes
+- **Flexibility**: Multiple methods for different use cases
+- **Simplified Syntax**: Single `--token-limit` option with method keywords or explicit limits
+
 ### Live Monitoring
 
 Real-time dashboard with automatic updates:

docs/guide/cli-options.md

@@ -209,15 +209,49 @@ ccusage blocks -r
 # Set token limit for warnings
 ccusage blocks --token-limit 500000
 ccusage blocks --token-limit max
+ccusage blocks --token-limit avg
+ccusage blocks --token-limit median
+
+# Limit calculation to recent sessions
+ccusage blocks --token-limit-sessions 10   # Use last 10 sessions (default)
+ccusage blocks --token-limit-sessions 5    # Use last 5 sessions
+
+# Combined token limit options
+ccusage blocks --token-limit avg --token-limit-sessions 10
+ccusage blocks --token-limit median --token-limit-sessions 15
 
 # Live monitoring mode
 ccusage blocks --live
 ccusage blocks --live --refresh-interval 2
+ccusage blocks --live --token-limit avg --token-limit-sessions 10
 
 # Customize session length
 ccusage blocks --session-length 5
 ```
 
+#### Token Limit Calculation Options
+
+| Option | Values | Description |
+|--------|---------|-------------|
+| `--token-limit` | `max`, `avg`, `median`, number | Set token limit (auto-calculated or explicit) |
+| `--token-limit-sessions` | number | Limit calculation to N most recent sessions |
+
+**Examples:**
+
+```bash
+# Conservative: Maximum of last 5 sessions
+ccusage blocks --token-limit max --token-limit-sessions 5
+
+# Balanced: Average of last 10 sessions  
+ccusage blocks --token-limit avg --token-limit-sessions 10
+
+# Robust: Median of all sessions (ignores outliers)
+ccusage blocks --token-limit median
+
+# Explicit limit (overrides calculation methods)
+ccusage blocks --token-limit 750000
+```
+
 ### MCP Server
 
 Options for MCP server:

docs/guide/live-monitoring.md

@@ -32,7 +32,7 @@ The dashboard refreshes every second, showing:
 
 ### Token Limits
 
-Set custom token limits for quota warnings:
+Set custom token limits for quota warnings with flexible calculation methods:
 
 ```bash
 # Use specific token limit
@@ -41,10 +41,76 @@ ccusage blocks --live -t 500000
 # Use highest previous session as limit (default)
 ccusage blocks --live -t max
 
-# Explicitly set max (same as default)
-ccusage blocks --live -t max
+# Use average of all previous sessions
+ccusage blocks --live -t avg
+
+# Use median of all previous sessions
+ccusage blocks --live -t median
+```
+
+#### Token Limit Calculation Methods
+
+Choose how the automatic token limit is calculated from your usage history:
+
+```bash
+# Maximum tokens from any session (default - conservative)
+ccusage blocks --live --token-limit max
+
+# Average tokens across all sessions (balanced)
+ccusage blocks --live --token-limit avg
+
+# Median tokens across all sessions (robust against outliers)
+ccusage blocks --live --token-limit median
 ```
 
+#### Limiting Calculation to Recent Sessions
+
+Control how many recent sessions are used for automatic limit calculation:
+
+```bash
+# Use only the 10 most recent sessions for calculation (default)
+ccusage blocks --live --token-limit-sessions 10
+
+# Use only the 5 most recent sessions (more responsive to recent patterns)
+ccusage blocks --live --token-limit-sessions 5
+
+# Use only the last session (equivalent to -t max with single session)
+ccusage blocks --live --token-limit-sessions 1
+```
+
+#### Combined Token Limit Options
+
+```bash
+# Average of last 10 sessions (balanced and recent)
+ccusage blocks --live --token-limit avg --token-limit-sessions 10
+
+# Median of last 15 sessions (robust and comprehensive)
+ccusage blocks --live --token-limit median --token-limit-sessions 15
+
+# Maximum of last 5 sessions (conservative but responsive)
+ccusage blocks --live --token-limit max --token-limit-sessions 5
+
+# Short aliases
+ccusage blocks --live --token-limit avg --token-limit-sessions 10
+```
+
+#### When to Use Each Method
+
+**Maximum (max)** - Most conservative approach:
+- Best for: Cost-conscious usage, avoiding overruns
+- Behavior: Sets limit to your highest usage session
+- Use when: You want strict budget control
+
+**Average (avg)** - Balanced approach:
+- Best for: Typical usage patterns, steady workflows
+- Behavior: Sets limit based on your typical usage
+- Use when: You have consistent usage patterns
+
+**Median (median)** - Robust against outliers:
+- Best for: Variable usage with occasional spikes
+- Behavior: Ignores extreme high/low sessions
+- Use when: You have mixed session types (quick questions + long projects)
+
 ### Refresh Interval
 
 Control update frequency:

src/_consts.ts

@@ -31,6 +31,12 @@ export const BLOCKS_COMPACT_WIDTH_THRESHOLD = 120;
  */
 export const BLOCKS_DEFAULT_TERMINAL_WIDTH = 120;
 
+/**
+ * Default number of recent completed sessions to use for token limit calculation in the blocks command
+ * Used when automatic token limit detection is enabled to analyze usage patterns
+ */
+export const DEFAULT_TOKEN_LIMIT_SESSIONS = 10;
+
 /**
  * Threshold percentage for considering costs as matching (0.1% tolerance)
  * Used in debug cost validation to allow for minor calculation differences