Initial commit
This commit is contained in:
Zhongwei Li
239
commands/contextune-usage.md
Normal file
239
commands/contextune-usage.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user