aboylabs/ai-agent-skills / skills/autonomous-ai-agents/hermes-agent
hermes-agent
FlaggedConfigure, extend, or contribute to Hermes Agent.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 39.3 KB |
| references/ecosystem-analysis.md | markdown | 13.9 KB |
| references/hermes-knowledge-base-workflow.md | markdown | 8.7 KB |
| references/tokscale-integration.md | markdown | 6.6 KB |
| references/vscode-extensions.md | markdown | 2.1 KB |
references/tokscale-integration.md
View on GitHub# tokscale Integration — Token Usage Tracking for Hermes
**Tool:** tokscale v2.1.0
**Author:** junhoyeo
**Stars:** 1,690
**Purpose:** Track token usage and costs across AI coding tools (Hermes, Code Assistant, Codex, Cursor, etc.)
---
## Installation
```bash
# Install via npm (Hermes uses custom node install)
npm install -g tokscale
# Verify installation
~/.hermes/node/bin/tokscale --version
# Output: tokscale 2.1.0
```
**Path resolution:** Hermes npm installs to `~/.hermes/node/bin/`, NOT the system default. The `tokscale` binary will be at `~/.hermes/node/bin/tokscale`.
---
## Setup
### Add alias for convenience
```bash
# Add to ~/.bashrc or ~/.zshrc
echo 'alias tokscale="$HOME/.hermes/node/bin/tokscale"' >> ~/.bashrc
source ~/.bashrc
# Now you can use:
tokscale models
```
### Auto-detection
tokscale automatically detects Hermes sessions by scanning `~/.hermes/state.db`. No configuration needed.
**Verification:**
```bash
tokscale clients
# Should show:
# Hermes Agent
# sessions: ~/.hermes/state.db ✓
# messages: 3.3K
```
---
## Usage
### Basic commands
```bash
# Usage by model
tokscale models
# Monthly report
tokscale monthly
# Hourly breakdown
tokscale hourly
# Interactive TUI
tokscale tui
# Check detected clients
tokscale clients
# Export as JSON
tokscale models --json
```
### Example output
```bash
$ tokscale models
```
```
AI token usage analytics
┌─────────────────────────────┬──────────┬────────────┬──────────┬────────┐
│ Model │ Messages │ Input │ Output │ Cost │
├─────────────────────────────┼──────────┼────────────┼──────────┼────────┤
│ claude-opus-4-6 │ 1,508 │ 15.2M │ 214K │ $81.51 │
│ claude-sonnet-4-5 │ 1,446 │ 5.0M │ 100K │ $16.55 │
│ claude-sonnet-4-5-thinking │ 348 │ 0 │ 80K │ $1.20 │
├─────────────────────────────┼──────────┼────────────┼──────────┼────────┤
│ Total │ 3,302 │ 20.2M │ 395K │ $99.26 │
└─────────────────────────────┴──────────┴────────────┴──────────┴────────┘
```
### JSON export for analysis
```bash
# Export current stats
tokscale models --json > ~/token-usage-$(date +%Y%m%d).json
# Example output:
{
"groupBy": "client,model",
"entries": [
{
"client": "hermes",
"model": "claude-opus-4-6",
"provider": "custom",
"input": 15227082,
"output": 214863,
"messageCount": 1508,
"cost": 81.50698499999997
}
],
"totalInput": 20242549,
"totalOutput": 395233,
"totalMessages": 3302,
"totalCost": 99.25893599999998
}
```
---
## Integration with Hermes Workflow
### Daily check
```bash
# Morning routine
tokscale models
# Check if costs are trending up
tokscale monthly
```
### Cost optimization
1. **Identify expensive models:**
```bash
tokscale models --json | jq '.entries | sort_by(.cost) | reverse | .[0:3]'
```
2. **Track usage patterns:**
```bash
tokscale hourly
# Identify peak usage times
```
3. **Set budget alerts** (manual):
```bash
# Export daily, compare to threshold
COST=$(tokscale models --json | jq '.totalCost')
if (( $(echo "$COST > 100" | bc -l) )); then
echo "Warning: Token costs exceeded $100"
fi
```
### Multi-tool tracking
tokscale tracks all AI coding tools in one place:
- Hermes Agent
- Code Assistant
- Codex CLI
- Cursor IDE
- OpenCode
- Copilot CLI
- And 15+ others
**View all:**
```bash
tokscale clients
```
---
## Troubleshooting
### Command not found after install
**Symptom:**
```bash
$ tokscale --version
bash: tokscale: command not found
```
**Cause:** Hermes npm is not in default PATH.
**Fix:**
```bash
# Option 1: Use full path
~/.hermes/node/bin/tokscale --version
# Option 2: Add alias (recommended)
echo 'alias tokscale="$HOME/.hermes/node/bin/tokscale"' >> ~/.bashrc
source ~/.bashrc
# Option 3: Add to PATH
echo 'export PATH="$HOME/.hermes/node/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
### Shows 0 messages for Hermes
**Symptom:**
```bash
$ tokscale clients
Hermes Agent
sessions: ~/.hermes/state.db ✗
messages: 0
```
**Cause:** Session database not found or not readable.
**Fix:**
```bash
# Check if database exists
ls -lh ~/.hermes/state.db
# Check permissions
chmod 644 ~/.hermes/state.db
# Verify Hermes is using the default location
hermes config path
```
### JSON export fails
**Symptom:**
```bash
$ tokscale models --json
Error: ...
```
**Cause:** Old version or corrupted data.
**Fix:**
```bash
# Update tokscale
npm install -g tokscale@latest
# Clear cache (if needed)
rm -rf ~/.config/tokscale/cache
```
---
## Advanced Usage
### Headless capture (for Codex CLI only)
tokscale can capture token usage from subprocess output:
```bash
tokscale headless codex chat -q "Hello"
```
**Note:** Headless capture only works for Codex CLI. Hermes usage is tracked automatically via `state.db`.
### Social platform (optional)
tokscale has a social platform for sharing usage stats:
```bash
# Login (opens browser for GitHub auth)
tokscale login
# Submit usage data
tokscale submit
# Generate year-in-review
tokscale wrapped
```
**Privacy:** Submission is opt-in. Local tracking works without login.
---
## Maintenance
### Update tokscale
```bash
npm install -g tokscale@latest
```
### Check for new features
```bash
tokscale --help
```
### Backup usage data
tokscale stores data in `~/.config/tokscale/`. Backup if needed:
```bash
tar -czf tokscale-backup-$(date +%Y%m%d).tar.gz ~/.config/tokscale/
```
---
## Integration Checklist
After installing tokscale:
- [ ] Add alias to `~/.bashrc` for convenience
- [ ] Run `tokscale clients` to verify Hermes detection
- [ ] Run `tokscale models` to see current usage
- [ ] Set up daily check routine (e.g., morning `tokscale models`)
- [ ] (Optional) Export JSON for custom analysis
- [ ] (Optional) Set up budget alerts
---
## References
- **GitHub:** https://github.com/junhoyeo/tokscale
- **NPM:** https://www.npmjs.com/package/tokscale
- **Hermes npm location:** `~/.hermes/node/bin/`
- **Session database:** `~/.hermes/state.db`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |