Skip to main content

/token-status - Context Token Status & Pivot Management

Display current context usage, check degradation patterns, and manage pivot strategies.

Usage​

# Show current status
/token-status

# Show detailed status with recommendations
/token-status --detail

# Execute a specific pivot strategy
/token-status --pivot chunk
/token-status --pivot compress
/token-status --pivot export
/token-status --pivot spawn

# Reset warning counters
/token-status --reset

# Configure thresholds
/token-status --set-alert 75
/token-status --set-critical 90

System Prompt​

When /token-status is invoked, execute the following:

1. Read Current State​

# Read token limit state
STATE_FILE="$HOME/.coditect/context-storage/token-limit-state.json"
if [ -f "$STATE_FILE" ]; then
    cat "$STATE_FILE" | python3 -m json.tool
else
    echo "No token state file found"
fi

# Check codi-watcher state for actual context %
WATCHER_FILE="$HOME/.coditect-data/context-storage/watcher-state.json"
if [ -f "$WATCHER_FILE" ]; then
    echo ""
    echo "=== Codi-Watcher State ==="
    cat "$WATCHER_FILE" | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'Context: {d.get(\"context_percent\", \"N/A\")}%')"
fi

2. Display Status Summary​

Format the output as:

╔══════════════════════════════════════════════════════════════╗
║                    TOKEN STATUS (H.8)                        ║
╠══════════════════════════════════════════════════════════════╣
║  Context Usage:  [████████░░░░░░░░░░░░]  42%                ║
║  Source:         codi-watcher | estimated                    ║
║  Tool Calls:     156                                         ║
║  Est. Tokens:    ~78,000 / 200,000                          ║
╠══════════════════════════════════════════════════════════════╣
║  Thresholds:     50% warn | 70% alert | 85% crit | 95% emrg ║
║  Current Level:  NORMAL | WARNING | ALERT | CRITICAL | EMRG ║
║  Warnings Shown: alert: 1, critical: 0                       ║
╠══════════════════════════════════════════════════════════════╣
║  Degradation:    None detected | [pattern list]              ║
║  Recommendation: Continue | Chunk | Compress | Export | Spawn║
╚══════════════════════════════════════════════════════════════╝

3. Generate Recommendations​

Based on current state, recommend actions:

LevelRecommendation
Normal (0-50%)Continue working normally
Warning (50-70%)Monitor, no action needed
Alert (70-85%)Consider chunking complex tasks
Critical (85-95%)Run /export soon
Emergency (95%+)Run /export immediately

4. Handle Options​

--detail​

Show additional information:

  • Full state JSON
  • Config settings
  • Recent log entries
  • Threshold history

--pivot [strategy]​

Invoke the orchestrator agent:

/agent token-limit-pivot-orchestrator "Execute [strategy] pivot strategy"

--reset​

Reset warning counters:

import json
from pathlib import Path

state_file = Path.home() / ".coditect" / "context-storage" / "token-limit-state.json"
if state_file.exists():
    state = json.loads(state_file.read_text())
    state["warnings_shown"] = {"warning": 0, "alert": 0, "critical": 0, "emergency": 0}
    state["thresholds_triggered"] = []
    state["auto_export_triggered"] = False
    state_file.write_text(json.dumps(state, indent=2))
    print("✓ Warning counters reset")

--set-alert N / --set-critical N​

Update thresholds in config:

import json
from pathlib import Path

config_file = Path.home() / ".coditect" / "config" / "token-pivot-config.json"
config = json.loads(config_file.read_text()) if config_file.exists() else {}
config.setdefault("thresholds", {})
# Update threshold
config["thresholds"]["alert"] = N / 100  # Convert to decimal
config_file.parent.mkdir(parents=True, exist_ok=True)
config_file.write_text(json.dumps(config, indent=2))
print(f"✓ Alert threshold set to {N}%")

Script Implementation​

For a quick status check, you can also use the script directly:

python3 ~/.coditect/scripts/token-status.py
python3 ~/.coditect/scripts/token-status.py --detail
python3 ~/.coditect/scripts/token-status.py --pivot export

Examples​

Basic Status Check​

> /token-status

╔══════════════════════════════════════════════════════════════╗
║                    TOKEN STATUS (H.8)                        ║
╠══════════════════════════════════════════════════════════════╣
║  Context Usage:  [████████░░░░░░░░░░░░]  42%                ║
║  Source:         estimated                                   ║
║  Tool Calls:     84                                          ║
║  Est. Tokens:    ~42,000 / 200,000                          ║
╠══════════════════════════════════════════════════════════════╣
║  Current Level:  NORMAL ✓                                    ║
║  Recommendation: Continue working normally                   ║
╚══════════════════════════════════════════════════════════════╝

High Usage Warning​

> /token-status

╔══════════════════════════════════════════════════════════════╗
║                    TOKEN STATUS (H.8)                        ║
╠══════════════════════════════════════════════════════════════╣
║  Context Usage:  [████████████████░░░░]  82%                ║
║  Source:         codi-watcher                                ║
║  Tool Calls:     312                                         ║
║  Est. Tokens:    ~164,000 / 200,000                         ║
╠══════════════════════════════════════════════════════════════╣
║  Current Level:  ⚠️ ALERT                                    ║
║  Warnings Shown: alert: 1                                    ║
╠══════════════════════════════════════════════════════════════╣
║  Recommendation: Consider running /export to preserve work   ║
║                  Or use: /token-status --pivot export        ║
╚══════════════════════════════════════════════════════════════╝

Execute Pivot​

> /token-status --pivot export

Executing export pivot strategy...

✓ Running /export...
✓ Running /cx...
✓ Creating checkpoint...

Pivot complete. Session preserved.

Files​

FilePurpose
~/PROJECTS/.coditect-data/context-storage/token-limit-state.jsonSession state
~/.coditect/config/token-pivot-config.jsonConfiguration
~/.coditect/logs/token-limit-hook.logDebug logs

5. Display Budget Utilization (ADR-111)​

When --budget flag is used OR when context usage is at WARNING level or above, also display token budget information from the Ralph Wiggum TokenEconomicsService:

import sys, os
from pathlib import Path

CORE_DIR = Path(os.environ.get('CODITECT_CORE', os.path.expanduser('~/.coditect')))
sys.path.insert(0, str(CORE_DIR / 'scripts' / 'core'))

try:
    from ralph_wiggum.token_economics import TokenEconomicsService
    service = TokenEconomicsService()

    # Get running totals
    totals = service.get_running_total()

    # Check budgets
    project_id = os.environ.get('CODITECT_PROJECT', '')
    budget_status = service.check_budget(project_id) if project_id else None
except ImportError:
    pass  # TokenEconomicsService not available

Display as additional section:

╠══════════════════════════════════════════════════════════════╣
║  Token Budget (ADR-111):                                     ║
║  Session Cost:  $2.45 (120K input / 18K output)             ║
║  Project Budget: $32.00 / $50.00 (64%) ⚠                   ║
║  Run /cost-report for full attribution                      ║
╚══════════════════════════════════════════════════════════════╝

--budget​

Show budget utilization alongside context usage:

/token-status --budget

This invokes the TokenEconomicsService to show cost alongside context metrics. For detailed cost analysis, use /cost-report.

Track: H (Framework) Task: H.8.4.5 Version: 2.0.0 Created: 2026-01-22 Updated: 2026-02-16