240 lines
6.3 KiB
Markdown
240 lines
6.3 KiB
Markdown
---
|
|
name: contextune:usage
|
|
description: Track and optimize Claude Code usage with intelligent recommendations
|
|
---
|
|
|
|
# Usage Tracking & Optimization
|
|
|
|
Contextune integrates with Claude Code's `/usage` command to provide intelligent context optimization, cost savings, and proactive warnings.
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Manual Paste (Most Accurate - Recommended)
|
|
|
|
1. Run Claude Code's usage command:
|
|
```
|
|
/usage
|
|
```
|
|
|
|
2. Copy the entire output
|
|
|
|
3. Run this command and paste when prompted:
|
|
```
|
|
/contextune:usage
|
|
```
|
|
|
|
### Option 2: Automatic Estimation
|
|
|
|
Contextune automatically estimates usage based on tracked operations (~85% accurate for Contextune tasks only).
|
|
|
|
View current estimates:
|
|
```
|
|
/contextune:stats
|
|
```
|
|
|
|
## What You Get
|
|
|
|
### Intelligent Recommendations
|
|
|
|
Based on your current usage, Contextune provides:
|
|
|
|
- **Model Selection**: Auto-switch to Haiku when approaching limits (87% cost savings)
|
|
- **Parallel Task Limits**: Recommended max concurrent tasks based on remaining quota
|
|
- **Proactive Warnings**: Alerts when approaching session or weekly limits
|
|
- **Opus Opportunities**: Suggestions to use Opus when quota is available for complex tasks
|
|
|
|
### Example Output
|
|
|
|
```
|
|
📊 Current Usage Analysis
|
|
═══════════════════════════════════════
|
|
|
|
📈 Usage Metrics:
|
|
Session: 19% (resets 1:00am America/New_York)
|
|
Weekly: 90% (resets Oct 29, 10:00pm America/New_York) ⚠️ CRITICAL
|
|
Opus: 0%
|
|
|
|
🎯 Status: CRITICAL
|
|
|
|
⚠️ Warnings:
|
|
• CRITICAL: 90% weekly usage (resets Oct 29, 10:00pm)
|
|
• You have ~10% capacity until Oct 29, 10:00pm
|
|
|
|
💡 Recommendations:
|
|
• Switch research tasks to Haiku (87% cost savings)
|
|
• Recommended max parallel tasks: 2
|
|
• Consider deferring non-critical tasks until weekly reset
|
|
• ✨ Opus available (0% used) - great for complex architecture tasks
|
|
|
|
📊 Historical Trends:
|
|
• Average daily usage: 12.9% (7-day trend)
|
|
• Projected usage to limit: [calculation]
|
|
• Cost savings from Haiku: $0.42 this week
|
|
```
|
|
|
|
## Usage Thresholds
|
|
|
|
| Weekly Usage | Status | Automatic Actions |
|
|
|-------------|--------|-------------------|
|
|
| 0-70% | ✅ Healthy | Normal operation, all models available |
|
|
| 71-85% | ⚠️ Warning | Suggest Haiku for research tasks |
|
|
| 86-95% | 🚨 Critical | Auto-switch to Haiku, limit parallel tasks |
|
|
| 96-100% | 🛑 Limit | Defer all tasks until reset |
|
|
|
|
## Integration Points
|
|
|
|
### Automatic Optimization
|
|
|
|
Once you've logged your usage, Contextune automatically:
|
|
|
|
1. **Research Tasks** (`/ctx:research`):
|
|
- Uses Haiku if weekly > 80% (saves $0.12 per task)
|
|
- Adjusts number of parallel agents based on quota
|
|
|
|
2. **Planning** (`/ctx:plan`):
|
|
- Warns if approaching limits
|
|
- Suggests task deferral if critical
|
|
- Recommends queue for after reset
|
|
|
|
3. **Execution** (`/ctx:execute`):
|
|
- Limits parallel tasks based on remaining quota
|
|
- Queues excess tasks for after reset
|
|
- Provides time estimates
|
|
|
|
## Manual Paste Format
|
|
|
|
Contextune can parse Claude Code's `/usage` output in this format:
|
|
|
|
```
|
|
Current session
|
|
[progress bar] 19% used
|
|
Resets 1:00am (America/New_York)
|
|
|
|
Current week (all models)
|
|
[progress bar] 90% used
|
|
Resets Oct 29, 10:00pm (America/New_York)
|
|
|
|
Current week (Opus)
|
|
[progress bar] 0% used
|
|
```
|
|
|
|
Just paste the entire block when prompted.
|
|
|
|
## Cost Savings Examples
|
|
|
|
### Research Task (3 parallel agents)
|
|
|
|
**Without optimization:**
|
|
- Model: Sonnet 3.5
|
|
- Cost: ~$0.24 per research task
|
|
- Weekly (10 tasks): $2.40
|
|
|
|
**With Contextune (90% usage):**
|
|
- Model: Haiku 4.5 (auto-switched)
|
|
- Cost: ~$0.02 per research task
|
|
- Weekly (10 tasks): $0.20
|
|
- **Saved: $2.20/week** ✅
|
|
|
|
### Parallel Execution (5 tasks)
|
|
|
|
**Without optimization:**
|
|
- Spawn all 5 tasks
|
|
- Risk hitting 100% limit mid-execution
|
|
- Failed tasks, wasted quota
|
|
|
|
**With Contextune (90% usage):**
|
|
- Execute 2 tasks now (within quota)
|
|
- Queue 3 tasks for after reset
|
|
- **Avoided: quota exhaustion** ✅
|
|
|
|
## Technical Details
|
|
|
|
### Data Storage
|
|
|
|
Usage snapshots are stored in `.contextune/observability.db`:
|
|
|
|
```sql
|
|
CREATE TABLE usage_history (
|
|
timestamp REAL PRIMARY KEY,
|
|
session_percent REAL,
|
|
weekly_percent REAL,
|
|
opus_percent REAL,
|
|
session_reset TEXT,
|
|
weekly_reset TEXT
|
|
);
|
|
```
|
|
|
|
### Token Estimation
|
|
|
|
When manual data isn't available, Contextune estimates usage from tracked operations:
|
|
|
|
```python
|
|
# Rough estimates (Claude 3.5 limits)
|
|
SESSION_LIMIT = 200,000 tokens # Per session limit
|
|
WEEKLY_LIMIT = 1,000,000 tokens # Per week limit
|
|
|
|
# Calculation
|
|
session_percent = (tracked_tokens / SESSION_LIMIT) * 100
|
|
```
|
|
|
|
**Accuracy**: ~85% for Contextune operations only (doesn't track other Claude Code sessions)
|
|
|
|
### Three-Tier Fallback
|
|
|
|
Contextune tries multiple approaches:
|
|
|
|
1. **Headless query** (experimental, may not be reliable)
|
|
2. **Token estimation** (85% accurate, automatic)
|
|
3. **Manual paste** (100% accurate, user-triggered)
|
|
|
|
## Troubleshooting
|
|
|
|
### "Unable to fetch usage data"
|
|
|
|
**Cause**: All automatic methods failed
|
|
**Solution**: Use manual paste workflow:
|
|
```
|
|
/usage
|
|
# Copy output
|
|
/contextune:usage
|
|
# Paste when prompted
|
|
```
|
|
|
|
### "Usage seems low compared to /usage"
|
|
|
|
**Cause**: Token estimation only tracks Contextune operations
|
|
**Solution**: Use manual paste for accurate data including all Claude Code sessions
|
|
|
|
### "Headless query taking too long"
|
|
|
|
**Cause**: Experimental feature timing out
|
|
**Solution**: Press Ctrl+C to cancel, use manual paste instead
|
|
|
|
## Privacy & Security
|
|
|
|
- Usage data stored locally in `.contextune/observability.db`
|
|
- No data sent to external servers
|
|
- Reset times preserved from Claude Code output
|
|
- Historical data helps optimize future tasks
|
|
|
|
## Related Commands
|
|
|
|
- `/usage` - Claude Code's native usage command
|
|
- `/context` - Claude Code's context management
|
|
- `/contextune:stats` - View Contextune detection statistics
|
|
- `/contextune:config` - Configure Contextune settings
|
|
|
|
## Future Enhancements
|
|
|
|
Planned for v1.0:
|
|
|
|
- **Predictive Analysis**: "At current rate, you'll hit 95% by Tuesday"
|
|
- **Budget Tracking**: "$X spent this week / $Y monthly budget"
|
|
- **Email Reports**: Weekly usage summaries
|
|
- **Team Coordination**: Share usage data across team
|
|
- **Official MCP Integration**: Direct API access (when available from Anthropic)
|
|
|
|
---
|
|
|
|
**Pro Tip**: Run `/contextune:usage` at the start of your session to enable intelligent optimization for all subsequent tasks.
|