r00tid-token-alert

监控会话 Token 用量，在 25%/50%/75%/90%/95% 阈值发送 Telegram 告警。

## 概述（中文）

监控会话 Token 用量，在 25%/50%/75%/90%/95% 阈值发送 Telegram 告警。

## 技能正文

# Token 告警 Skill

🚨 **监控 session tokens and get 告警s at 75%/90%/95%**

## 概述

The Token 告警 Skill automatically monitors your Clawdbot session token usage and sends 告警s when you approach limits. 切勿 lose context mid-conversation again!

## 功能

- ✅ **6-Level Threshold System** - Alerts at 25%, 50%, 75%, 90%, 95%, 100%
- ✅ **Material Design Progress Bar** - Box-style (▰/▱) with color gradients
- ✅ **Rich UI Dashboard** - Interactive HTML 仪表板 with animations
- ✅ **Session Status** - Shows current token usage on demand
- ✅ **Telegram Alerts** - 获取 notified before hitting limits
- ✅ **HEARTBEAT 集成** - 可选 automated checks
- ✅ **Stateless** - No state file needed, calculates on-demand
- ✅ **Session Estimates** - Predicts remaining sessions (~50k avg)

## 用法

### Interactive Dashboard

Ask Grym:
- "Show token 仪表板"
- "Open 仪表板"

Or run directly:
```bash
python3 ~/clawd/skills/token-alert/scripts/show_dashboard.py
```

### Terminal Check

Ask Grym:
- "Wie viele Tokens habe ich noch übrig?"
- "检查 token status"
- "Token 用量?"

Or run:
```bash
python3 ~/clawd/skills/token-alert/scripts/check.py
```

### Automatic Alerts

Grym will automatically 告警 you when:
- 🟡 **25%** - Low warning (~150k tokens left)
- 🟠 **50%** - Medium warning (~100k tokens left)
- 🔶 **75%** - High warning (~50k tokens left)
- 🔴 **90%** - Critical warning (~20k tokens left)
- 🚨 **95%** - Emergency! (<10k tokens left)

### 示例 Output

```
🔶 Token Alert: Achtung!

🔶 ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱ 78.0%
156,000 / 200,000 Tokens verwendet

⚠️ Status: High Warning (Rot-Orange Zone)
💡 Verbleibend: ~44k Tokens
⏰ Geschätzte Sessions: <1 Session

🔧 Empfehlung:
   ✅ Wichtige Entscheidungen jetzt treffen
   ✅ Neue Session vorbereiten
   ✅ Token-sparend arbeiten
```

## 安装

```bash
# Via ClawdHub
clawdhub install token-alert

# Manual
cd ~/clawd/skills
git clone https://github.com/r00tid/clawdbot-token-alert token-alert
```

## 配置

### HEARTBEAT 集成 (Optional)

Add to `~/clawd/HEARTBEAT.md`:

```markdown
### Token Usage Check (täglich)
- [ ] `python3 ~/clawd/skills/token-alert/scripts/check.py`
- **Warning ab 70%:** "⚠️ Session bei XX% - Token-Sparend ab jetzt!"
```

## 工作原理

1. Uses Clawdbot's `session_status` tool
2. Calculates percentage of token usage
3. Compares against 阈值s (75%, 90%, 95%)
4. 发送 Telegram 告警 if 阈值 crossed

## 技术细节

### Files

```
skills/token-alert/
├── SKILL.md                    # This file
├── README.md                   # GitHub documentation
├── LICENSE                     # MIT License
├── .clawdhub/
│   └── manifest.json           # ClawdHub metadata
├── assets/
│   ├── dashboard-78-high.png   # Screenshot (High Warning)
│   └── dashboard-96-emergency.png  # Screenshot (Emergency)
└── scripts/
    ├── check.py                # Token checker (Terminal)
    ├── dashboard.html          # Rich UI dashboard
    └── show_dashboard.py       # Dashboard launcher
```

### 依赖

- Python 3.8+
- Clawdbot session_status tool
- Optional: Telegram channel configured

### Script API

```python
# scripts/check.py
def get_session_tokens():
    """Get current session token usage via session_status tool"""
    
def check_thresholds(percent):
    """Check if usage exceeds thresholds"""
    
def format_alert(used, limit, percent, level):
    """Format alert message for Telegram"""
```

## 何时使用

- **在…之前 long tasks** - 检查 if you have enough tokens
- **Mid-conversation** - 监控 usage during long sessions
- **Daily check** - Add to HEARTBEAT for automatic monitoring

## 限制

- Only monitors session tokens (not Claude.ai API limits)
- 需要 active Clawdbot session
- 告警 frequency can be noisy if near 阈值

## 未来增强

- [ ] Claude.ai API limits scraping (optional)
- [ ] Historical token usage tracking
- [ ] Weekly/monthly usage reports
- [ ] 集成 with `token-router` skill

## Support

- GitHub Issues: https://github.com/r00tid/clawdbot-token-告警/issues
- ClawdHub: https://clawdhub.com/skills/token-告警
- Docs: https://docs.clawd.bot

## 许可证

MIT License - See LICENSE file

---

Built with ❤️ by Grym 🥜