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)

Run Claude Code's usage command:
```
/usage
```
Copy the entire output
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:

Research Tasks (/ctx:research):
- Uses Haiku if weekly > 80% (saves $0.12 per task)
- Adjusts number of parallel agents based on quota
Planning (/ctx:plan):
- Warns if approaching limits
- Suggests task deferral if critical
- Recommends queue for after reset
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:

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:

# 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:

Headless query (experimental, may not be reliable)
Token estimation (85% accurate, automatic)
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.

/contextune-usage