Skip to content

Commit 18ea04f

Browse files
committed
docs(hermes): document Hermes Agent source
Add Hermes Agent to the README, guide navigation, source overview pages, environment variable reference, and configuration namespace documentation. Document the local state.db location, HERMES_HOME override, focused commands, token and cost behavior, and troubleshooting guidance for users without requiring local Hermes data in tests.
1 parent 60d27bc commit 18ea04f

9 files changed

Lines changed: 121 additions & 30 deletions

File tree

‎apps/ccusage/README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
2626
## Supported Sources
2727

28-
The main CLI tool for analyzing Claude Code, Codex, OpenCode, Amp, and pi-agent usage from local data. Track daily, weekly, monthly, and session-based usage with beautiful tables.
28+
The main CLI tool for analyzing Claude Code, Codex, OpenCode, Amp, pi-agent, and Hermes Agent usage from local data. Track daily, weekly, monthly, and session-based usage with beautiful tables.
2929

3030
## Installation
3131

@@ -64,6 +64,7 @@ bunx ccusage codex daily --speed fast
6464
bunx ccusage opencode weekly
6565
bunx ccusage amp session
6666
bunx ccusage pi daily --pi-path /path/to/sessions
67+
bunx ccusage hermes daily
6768
bunx ccusage pi daily --pi-path /path/to/sessions,/archive/pi/sessions
6869

6970
# Explicit unified report
@@ -89,7 +90,7 @@ bunx ccusage monthly --compact # Compact monthly report
8990
- 📊 **Daily Report**: View token usage and costs aggregated by date
9091
- 📅 **Monthly Report**: View token usage and costs aggregated by month
9192
- 💬 **Session Report**: View usage grouped by conversation sessions
92-
- 🤖 **Unified CLI Reports**: View Claude Code, Codex, OpenCode, Amp, and pi-agent usage from one CLI
93+
- 🤖 **Unified CLI Reports**: View Claude Code, Codex, OpenCode, Amp, pi-agent, and Hermes Agent usage from one CLI
9394
- ⏰ **5-Hour Blocks Report**: Track usage within Claude's billing windows with active block monitoring
9495
- 🚀 **Statusline Integration**: Compact usage display for Claude Code status bar hooks (Beta)
9596
- 🤖 **Model Tracking**: See which models are used across supported sources

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ export default defineConfig({
7373
{ text: 'OpenCode', link: '/guide/opencode/' },
7474
{ text: 'Amp', link: '/guide/amp/' },
7575
{ text: 'pi-agent', link: '/guide/pi/' },
76+
{ text: 'Hermes Agent', link: '/guide/hermes/' },
7677
],
7778
},
7879
{

‎docs/guide/all-reports.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ ccusage daily --all
2525

2626
## How Unified Views Work
2727

28-
ccusage detects local usage files from Claude Code, Codex, OpenCode, Amp, and pi-agent. The same daily, weekly, monthly, and session views can run in two modes:
28+
ccusage detects local usage files from Claude Code, Codex, OpenCode, Amp, pi-agent, and Hermes Agent. The same daily, weekly, monthly, and session views can run in two modes:
2929

3030
| Mode | Command example | What it shows |
3131
| ------- | ---------------------- | --------------------------------------- |
@@ -37,13 +37,14 @@ Unified tables include an **Agent** column so you can compare sources in one vie
3737

3838
## Supported Sources
3939

40-
| Source | Namespace | Example focused view |
41-
| ----------- | ---------- | ------------------------- |
42-
| Claude Code | `claude` | `ccusage claude daily` |
43-
| Codex | `codex` | `ccusage codex daily` |
44-
| OpenCode | `opencode` | `ccusage opencode weekly` |
45-
| Amp | `amp` | `ccusage amp session` |
46-
| pi-agent | `pi` | `ccusage pi monthly` |
40+
| Source | Namespace | Example focused view |
41+
| ------------ | ---------- | ------------------------- |
42+
| Claude Code | `claude` | `ccusage claude daily` |
43+
| Codex | `codex` | `ccusage codex daily` |
44+
| OpenCode | `opencode` | `ccusage opencode weekly` |
45+
| Amp | `amp` | `ccusage amp session` |
46+
| pi-agent | `pi` | `ccusage pi monthly` |
47+
| Hermes Agent | `hermes` | `ccusage hermes daily` |
4748

4849
## When to Focus a Source
4950

@@ -55,6 +56,7 @@ ccusage claude daily --mode display
5556
ccusage opencode session --json
5657
ccusage amp monthly --compact
5758
ccusage pi session --pi-path /path/to/sessions
59+
ccusage hermes daily --json
5860
```
5961

6062
## Next Steps

‎docs/guide/config-files.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -176,7 +176,7 @@ Override shared defaults for specific unified reports and legacy Claude commands
176176

177177
### Source-Specific Configuration
178178

179-
Use data source namespaces to set defaults and report overrides. Supported namespaces are `claude`, `codex`, `opencode`, `amp`, and `pi`.
179+
Use data source namespaces to set defaults and report overrides. Supported namespaces are `claude`, `codex`, `opencode`, `amp`, `pi`, and `hermes`.
180180

181181
```json
182182
{
@@ -208,6 +208,13 @@ Use data source namespaces to set defaults and report overrides. Supported names
208208
"defaults": {
209209
"piPath": "/path/to/pi/sessions,/archive/pi/sessions"
210210
}
211+
},
212+
"hermes": {
213+
"commands": {
214+
"daily": {
215+
"json": true
216+
}
217+
}
211218
}
212219
}
213220
```
@@ -218,6 +225,7 @@ This configuration affects source-focused commands such as:
218225
ccusage codex daily
219226
ccusage opencode weekly
220227
ccusage pi daily
228+
ccusage hermes daily
221229
```
222230

223231
Source-specific settings are also applied when running unified reports such as `ccusage daily`. In that case, each source receives its own merged options before data is loaded.

‎docs/guide/configuration.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,15 @@ export CODEX_HOME="$HOME/.codex"
5353
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode"
5454
export AMP_DATA_DIR="$HOME/.local/share/amp"
5555
export PI_AGENT_DIR="$HOME/.pi/agent/sessions"
56+
export HERMES_HOME="$HOME/.hermes"
5657
```
5758

5859
Use comma-separated directories when you want reports to combine multiple profiles or archives:
5960

6061
```bash
6162
export CODEX_HOME="$HOME/.codex,$HOME/.codex-work"
6263
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode,/archive/opencode"
64+
export HERMES_HOME="$HOME/.hermes,/archive/hermes"
6365
```
6466

6567
2. **Create a configuration file** for your preferences:
@@ -104,7 +106,7 @@ For individual developers working on multiple projects:
104106

105107
### Multiple Sources
106108

107-
Configure Claude Code, Codex, OpenCode, Amp, and pi-agent separately with data source namespaces:
109+
Configure Claude Code, Codex, OpenCode, Amp, pi-agent, and Hermes Agent separately with data source namespaces:
108110

109111
```json
110112
// ~/.config/claude/ccusage.json

‎docs/guide/environment-variables.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,14 @@ ccusage supports several environment variables for configuration and customizati
66

77
ccusage detects supported data source files from conventional locations by default. Set these variables when your data lives somewhere else. Each value can be one directory or a comma-separated list of directories:
88

9-
| Variable | Agent | Default |
10-
| ------------------- | ----------- | ---------------------------------- |
11-
| `CLAUDE_CONFIG_DIR` | Claude Code | `~/.config/claude` and `~/.claude` |
12-
| `CODEX_HOME` | Codex | `~/.codex` |
13-
| `OPENCODE_DATA_DIR` | OpenCode | `~/.local/share/opencode` |
14-
| `AMP_DATA_DIR` | Amp | `~/.local/share/amp` |
15-
| `PI_AGENT_DIR` | pi-agent | `~/.pi/agent/sessions` |
9+
| Variable | Agent | Default |
10+
| ------------------- | ------------ | ---------------------------------- |
11+
| `CLAUDE_CONFIG_DIR` | Claude Code | `~/.config/claude` and `~/.claude` |
12+
| `CODEX_HOME` | Codex | `~/.codex` |
13+
| `OPENCODE_DATA_DIR` | OpenCode | `~/.local/share/opencode` |
14+
| `AMP_DATA_DIR` | Amp | `~/.local/share/amp` |
15+
| `PI_AGENT_DIR` | pi-agent | `~/.pi/agent/sessions` |
16+
| `HERMES_HOME` | Hermes Agent | `~/.hermes` |
1617

1718
Example:
1819

@@ -21,6 +22,7 @@ export CODEX_HOME="/path/to/codex,/archive/codex"
2122
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
2223
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
2324
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
25+
export HERMES_HOME="/path/to/hermes,/archive/hermes"
2426
ccusage daily
2527
```
2628

@@ -198,7 +200,7 @@ To see which environment variables are being used:
198200

199201
```bash
200202
# Show all environment variables
201-
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|PI_AGENT|CCUSAGE|LOG_LEVEL"
203+
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|PI_AGENT|HERMES|CCUSAGE|LOG_LEVEL"
202204

203205
# Debug mode shows environment variable usage
204206
LOG_LEVEL=4 ccusage daily --debug

‎docs/guide/getting-started.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,7 @@ If ccusage shows no data, check:
156156
- OpenCode: `${OPENCODE_DATA_DIR:-~/.local/share/opencode}`
157157
- Amp: `${AMP_DATA_DIR:-~/.local/share/amp}`
158158
- pi-agent: `${PI_AGENT_DIR:-~/.pi/agent/sessions}`
159+
- Hermes Agent: `${HERMES_HOME:-~/.hermes}/state.db`
159160

160161
### Custom Data Directory
161162

@@ -167,6 +168,7 @@ export CODEX_HOME="/path/to/codex"
167168
export OPENCODE_DATA_DIR="/path/to/opencode"
168169
export AMP_DATA_DIR="/path/to/amp"
169170
export PI_AGENT_DIR="/path/to/pi/sessions"
171+
export HERMES_HOME="/path/to/hermes"
170172
```
171173

172174
Each source-specific path variable can also contain comma-separated directories:
@@ -176,6 +178,7 @@ export CODEX_HOME="/path/to/codex,/archive/codex"
176178
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
177179
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
178180
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
181+
export HERMES_HOME="/path/to/hermes,/archive/hermes"
179182
```
180183

181184
## Getting Help

‎docs/guide/hermes/index.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Hermes Agent Data Source (Beta)
2+
3+
> Hermes Agent support is experimental. Expect changes while both ccusage and [Hermes Agent](https://github.com/NousResearch/hermes-agent) continue to evolve.
4+
5+
ccusage can read Hermes Agent session usage from its local SQLite state database. The adapter uses the same focused and unified report shape as the other local coding CLI data sources.
6+
7+
## Focused Views
8+
9+
::: code-group
10+
11+
```bash [bunx (Recommended)]
12+
bunx ccusage hermes --help
13+
```
14+
15+
```bash [npx]
16+
npx ccusage@latest hermes --help
17+
```
18+
19+
```bash [pnpm]
20+
pnpm dlx ccusage hermes --help
21+
```
22+
23+
:::
24+
25+
## Data Source
26+
27+
The CLI reads Hermes Agent session rows from `$HERMES_HOME/state.db`. When `HERMES_HOME` is not set, ccusage checks `~/.hermes/state.db`.
28+
29+
```bash
30+
HERMES_HOME="$HOME/.hermes" ccusage hermes daily
31+
```
32+
33+
```text
34+
~/.hermes/
35+
└── state.db
36+
```
37+
38+
## Report Views
39+
40+
| Focused view | Description | See also |
41+
| ------------------------ | -------------------------------- | --------------------------------------- |
42+
| `ccusage hermes daily` | Aggregate usage by date | [Daily Usage](/guide/daily-reports) |
43+
| `ccusage hermes monthly` | Aggregate usage by month | [Monthly Usage](/guide/monthly-reports) |
44+
| `ccusage hermes session` | Group usage by Hermes session ID | [Session Usage](/guide/session-reports) |
45+
46+
These views support `--json`, `--compact`, `--offline`, `--since`, `--until`, and `--timezone`.
47+
48+
## What Gets Calculated
49+
50+
- **Token usage** - Reads input, output, cache read, cache write, and reasoning token totals from Hermes session rows.
51+
- **Total tokens** - Includes reasoning tokens in the total token count.
52+
- **Costs** - Prefers recorded actual cost, then recorded estimated cost, then calculates from LiteLLM pricing when token data is available.
53+
- **Message count** - Preserves Hermes `message_count` in JSON metadata.
54+
55+
## Environment Variables
56+
57+
| Variable | Description |
58+
| ------------- | --------------------------------------------------------------------------------- |
59+
| `HERMES_HOME` | Override the directory containing `state.db`; comma-separated roots are supported |
60+
| `LOG_LEVEL` | Adjust verbosity (0 silent ... 5 trace) |
61+
62+
## Troubleshooting
63+
64+
::: details No Hermes Agent usage data found
65+
Ensure the database exists at `$HERMES_HOME/state.db` or `~/.hermes/state.db`. If your database lives elsewhere, set `HERMES_HOME` to the directory that contains `state.db`.
66+
:::
67+
68+
::: details Costs showing as $0.00
69+
If Hermes has no recorded cost and a model is not in LiteLLM's database, the calculated cost will be $0.00.
70+
:::

‎docs/guide/index.md‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
![ccusage daily report showing token usage and costs by date](/screenshot.png)
44

5-
**ccusage** is a local CLI for understanding coding (agent) CLI token usage and estimated costs across Claude Code, Codex, OpenCode, Amp, and pi-agent.
5+
**ccusage** is a local CLI for understanding coding (agent) CLI token usage and estimated costs across Claude Code, Codex, OpenCode, Amp, pi-agent, and Hermes Agent.
66

7-
The original **“cc”** came from **C**laude **C**ode usage and now also fits **C**odex **C**LI usage. As OpenCode, Amp, pi-agent, and other coding (agent) CLIs became part of the same workflow, ccusage expanded into a general name for local coding CLI usage analysis.
7+
The original **“cc”** came from **C**laude **C**ode usage and now also fits **C**odex **C**LI usage. As OpenCode, Amp, pi-agent, Hermes Agent, and other coding (agent) CLIs became part of the same workflow, ccusage expanded into a general name for local coding CLI usage analysis.
88

99
## The Problem
1010

@@ -19,7 +19,7 @@ Modern coding (agent) CLI usage is split across several local data formats. That
1919

2020
ccusage reads the local usage files that coding CLIs already generate and provides:
2121

22-
- **All Sources by Default** - Claude Code, Codex, OpenCode, Amp, and pi-agent in one CLI
22+
- **All Sources by Default** - Claude Code, Codex, OpenCode, Amp, pi-agent, and Hermes Agent in one CLI
2323
- **Usage Views** - Daily, weekly, monthly, and session-based breakdowns
2424
- **Cost Analysis** - Estimated costs based on token usage and model pricing
2525
- **Focused Data Source Views** - Start with all detected sources, then narrow the same usage views to one source when needed
@@ -72,13 +72,14 @@ Each data source page covers the details that only apply to that source, includi
7272

7373
ccusage reads from local coding CLI data directories:
7474

75-
| Agent | ID | Default data location |
76-
| ----------- | ---------- | ----------------------------------------------- |
77-
| Claude Code | `claude` | `~/.config/claude/projects/`, `~/.claude/` |
78-
| Codex | `codex` | `${CODEX_HOME:-~/.codex}` |
79-
| OpenCode | `opencode` | `${OPENCODE_DATA_DIR:-~/.local/share/opencode}` |
80-
| Amp | `amp` | `${AMP_DATA_DIR:-~/.local/share/amp}` |
81-
| pi-agent | `pi` | `${PI_AGENT_DIR:-~/.pi/agent/sessions}` |
75+
| Agent | ID | Default data location |
76+
| ------------ | ---------- | ----------------------------------------------- |
77+
| Claude Code | `claude` | `~/.config/claude/projects/`, `~/.claude/` |
78+
| Codex | `codex` | `${CODEX_HOME:-~/.codex}` |
79+
| OpenCode | `opencode` | `${OPENCODE_DATA_DIR:-~/.local/share/opencode}` |
80+
| Amp | `amp` | `${AMP_DATA_DIR:-~/.local/share/amp}` |
81+
| pi-agent | `pi` | `${PI_AGENT_DIR:-~/.pi/agent/sessions}` |
82+
| Hermes Agent | `hermes` | `${HERMES_HOME:-~/.hermes}/state.db` |
8283

8384
The tool automatically detects available data and aggregates all supported coding CLIs by default.
8485
Each source-specific environment variable can also contain comma-separated directories, which lets unified reports combine current profiles and archives.
@@ -102,6 +103,7 @@ ccusage codex daily --speed fast
102103
ccusage opencode weekly
103104
ccusage amp session
104105
ccusage pi monthly
106+
ccusage hermes daily
105107
```
106108

107109
Use `ccusage <source> <report>` only when you want to narrow a report to one source.

0 commit comments

Comments
 (0)