Skip to content

Commit 35cb05e

Browse files
authored
feat(kilo): add Kilo usage adapter (#1032)
* feat(kilo): add Kilo usage adapter Add a Kilo CLI adapter that reads local kilo.db SQLite usage rows from KILO_DATA_DIR or the default data directory. Wire Kilo into focused and all-agent reports, config namespaces, generated schema, and docs so it behaves like the other local usage sources. Use recorded costs when Kilo provides them, fall back to LiteLLM pricing otherwise, and skip timestamp-less rows to avoid assigning usage to the wrong day. Add adapter tests plus CLI JSON snapshot coverage for the new command surface. * fix(kilo): honor recorded zero costs Trust Kilo recorded costs whenever present, including explicit zero-cost rows, before falling back to LiteLLM token pricing. Also simplify synchronous source detection and derive config schema agent properties from the configured agent key list. * fix(kilo): scope fallback dedupe keys Scope fallback row-id dedupe keys to the source Kilo database path so separate KILO_DATA_DIR databases cannot drop valid rows when a message lacks an embedded id. Add regression coverage for fallback row-id collisions and label the Kilo docs directory-tree fence for markdown lint. * docs(kilo): clarify recorded zero costs Align the Kilo cost calculation guide with the loader behavior introduced in the zero-cost fix. The adapter treats any non-null recorded cost as authoritative, including a recorded 0, before falling back to LiteLLM pricing. * chore(schema): format generated config schema Keep the generated config schema formatting in sync with the pre-commit generator after merging origin/main into the Kilo adapter branch.
1 parent 1727a60 commit 35cb05e

21 files changed

Lines changed: 766 additions & 19 deletions

File tree

‎apps/ccusage/README.md‎

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

27-
The main CLI tool for analyzing Claude Code, Codex, OpenCode, Amp, pi-agent, GitHub Copilot CLI, and Gemini CLI usage from local data. Track daily, weekly, monthly, and session-based usage with beautiful tables.
27+
The main CLI tool for analyzing Claude Code, Codex, OpenCode, Amp, pi-agent, Kilo, GitHub Copilot CLI, and Gemini CLI usage from local data. Track daily, weekly, monthly, and session-based usage with beautiful tables.
2828

2929
## Installation
3030

@@ -68,6 +68,7 @@ bunx ccusage claude daily --mode display
6868
bunx ccusage codex daily --speed fast
6969
bunx ccusage opencode weekly
7070
bunx ccusage amp session
71+
bunx ccusage kilo daily
7172
bunx ccusage copilot daily
7273
bunx ccusage gemini daily
7374
bunx ccusage pi daily --pi-path /path/to/sessions
@@ -96,7 +97,7 @@ bunx ccusage monthly --compact # Compact monthly report
9697
- 📊 **Daily Report**: View token usage and costs aggregated by date
9798
- 📅 **Monthly Report**: View token usage and costs aggregated by month
9899
- 💬 **Session Report**: View usage grouped by conversation sessions
99-
- 🤖 **Unified CLI Reports**: View Claude Code, Codex, OpenCode, Amp, pi-agent, GitHub Copilot CLI, and Gemini CLI usage from one CLI
100+
- 🤖 **Unified CLI Reports**: View Claude Code, Codex, OpenCode, Amp, pi-agent, Kilo, GitHub Copilot CLI, and Gemini CLI usage from one CLI
100101
- ⏰ **5-Hour Blocks Report**: Track usage within Claude's billing windows with active block monitoring
101102
- 🚀 **Statusline Integration**: Compact usage display for Claude Code status bar hooks (Beta)
102103
- 🤖 **Model Tracking**: See which models are used across supported sources

‎apps/ccusage/config-schema.json‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -715,6 +715,33 @@
715715
},
716716
"type": "object"
717717
},
718+
"KiloCommandsConfig": {
719+
"additionalProperties": false,
720+
"properties": {
721+
"daily": {
722+
"$ref": "#/definitions/SharedOptions"
723+
},
724+
"monthly": {
725+
"$ref": "#/definitions/SharedOptions"
726+
},
727+
"session": {
728+
"$ref": "#/definitions/SharedOptions"
729+
}
730+
},
731+
"type": "object"
732+
},
733+
"KiloConfig": {
734+
"additionalProperties": false,
735+
"properties": {
736+
"commands": {
737+
"$ref": "#/definitions/KiloCommandsConfig"
738+
},
739+
"defaults": {
740+
"$ref": "#/definitions/SharedOptions"
741+
}
742+
},
743+
"type": "object"
744+
},
718745
"OpenCodeCommandsConfig": {
719746
"additionalProperties": false,
720747
"properties": {
@@ -1280,6 +1307,15 @@
12801307
"description": "Gemini CLI configuration.",
12811308
"markdownDescription": "Gemini CLI configuration."
12821309
},
1310+
"kilo": {
1311+
"allOf": [
1312+
{
1313+
"$ref": "#/definitions/KiloConfig"
1314+
}
1315+
],
1316+
"description": "Kilo configuration.",
1317+
"markdownDescription": "Kilo configuration."
1318+
},
12831319
"opencode": {
12841320
"allOf": [
12851321
{

‎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: 'Kilo', link: '/guide/kilo/' },
7677
{ text: 'GitHub Copilot CLI', link: '/guide/copilot/' },
7778
{ text: 'Gemini CLI', link: '/guide/gemini/' },
7879
],

‎docs/guide/all-reports.md‎

Lines changed: 3 additions & 1 deletion
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, pi-agent, GitHub Copilot CLI, and Gemini CLI. 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, Kilo, GitHub Copilot CLI, and Gemini CLI. The same daily, weekly, monthly, and session views can run in two modes:
2929

3030
| Mode | Command example | What it shows |
3131
| ------- | ---------------------- | --------------------------------------- |
@@ -44,6 +44,7 @@ Unified tables include an **Agent** column so you can compare sources in one vie
4444
| OpenCode | `opencode` | `ccusage opencode weekly` |
4545
| Amp | `amp` | `ccusage amp session` |
4646
| pi-agent | `pi` | `ccusage pi monthly` |
47+
| Kilo | `kilo` | `ccusage kilo daily` |
4748
| Copilot CLI | `copilot` | `ccusage copilot daily` |
4849
| Gemini CLI | `gemini` | `ccusage gemini daily` |
4950

@@ -57,6 +58,7 @@ ccusage claude daily --mode display
5758
ccusage opencode session --json
5859
ccusage amp monthly --compact
5960
ccusage pi session --pi-path /path/to/sessions
61+
ccusage kilo session
6062
ccusage copilot daily --json
6163
ccusage gemini session --json
6264
```

‎docs/guide/claude/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Claude Code Data Source
22

3-
ccusage can read Claude Code usage data as one of its supported local data sources. Claude Code is no longer treated as the only ccusage target; it uses the same unified and focused report model as Codex, OpenCode, Amp, pi-agent, and GitHub Copilot CLI.
3+
ccusage can read Claude Code usage data as one of its supported local data sources. Claude Code is no longer treated as the only ccusage target; it uses the same unified and focused report model as Codex, OpenCode, Amp, pi-agent, Kilo, GitHub Copilot CLI, and Gemini CLI.
44

55
## Focused Views
66

@@ -75,7 +75,7 @@ export CLAUDE_CONFIG_DIR="~/.config/claude,/backup/claude-archive"
7575
ccusage claude monthly
7676
```
7777

78-
For Codex, OpenCode, Amp, pi-agent, and GitHub Copilot CLI data locations, use the source-specific environment variables listed in [Environment Variables](/guide/environment-variables).
78+
For Codex, OpenCode, Amp, pi-agent, Kilo, GitHub Copilot CLI, and Gemini CLI data locations, use the source-specific environment variables listed in [Environment Variables](/guide/environment-variables).
7979

8080
### Directory Detection
8181

‎docs/guide/codex/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
> ⚠️ Codex log support is experimental while the Codex CLI log format continues to evolve.
66
7-
ccusage can read OpenAI Codex CLI session logs as one of its supported local data sources. Codex uses the same unified and focused report model as Claude Code, OpenCode, Amp, pi-agent, and GitHub Copilot CLI.
7+
ccusage can read OpenAI Codex CLI session logs as one of its supported local data sources. Codex uses the same unified and focused report model as Claude Code, OpenCode, Amp, pi-agent, Kilo, GitHub Copilot CLI, and Gemini CLI.
88

99
## Focused Views
1010

‎docs/guide/config-files.md‎

Lines changed: 7 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`, `pi`, `copilot`, and `gemini`.
179+
Use data source namespaces to set defaults and report overrides. Supported namespaces are `claude`, `codex`, `opencode`, `amp`, `pi`, `kilo`, `copilot`, and `gemini`.
180180

181181
```json
182182
{
@@ -209,6 +209,11 @@ Use data source namespaces to set defaults and report overrides. Supported names
209209
"piPath": "/path/to/pi/sessions,/archive/pi/sessions"
210210
}
211211
},
212+
"kilo": {
213+
"defaults": {
214+
"offline": true
215+
}
216+
},
212217
"copilot": {
213218
"defaults": {
214219
"offline": true
@@ -228,6 +233,7 @@ This configuration affects source-focused commands such as:
228233
ccusage codex daily
229234
ccusage opencode weekly
230235
ccusage pi daily
236+
ccusage kilo daily
231237
ccusage copilot monthly
232238
ccusage gemini daily
233239
```

‎docs/guide/configuration.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ export GEMINI_DATA_DIR="$HOME/.gemini/tmp"
5454
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode"
5555
export AMP_DATA_DIR="$HOME/.local/share/amp"
5656
export PI_AGENT_DIR="$HOME/.pi/agent/sessions"
57+
export KILO_DATA_DIR="$HOME/.local/share/kilo"
5758
export COPILOT_OTEL_FILE_EXPORTER_PATH="$HOME/.copilot/otel/copilot-otel.jsonl"
5859
```
5960

@@ -63,6 +64,7 @@ Use comma-separated directories when you want reports to combine multiple profil
6364
export CODEX_HOME="$HOME/.codex,$HOME/.codex-work"
6465
export GEMINI_DATA_DIR="$HOME/.gemini/tmp,/backup/gemini/tmp"
6566
export OPENCODE_DATA_DIR="$HOME/.local/share/opencode,/archive/opencode"
67+
export KILO_DATA_DIR="$HOME/.local/share/kilo,/backup/kilo"
6668
```
6769

6870
2. **Create a configuration file** for your preferences:
@@ -107,7 +109,7 @@ For individual developers working on multiple projects:
107109

108110
### Multiple Sources
109111

110-
Configure Claude Code, Codex, OpenCode, Amp, pi-agent, GitHub Copilot CLI, and Gemini CLI separately with data source namespaces:
112+
Configure Claude Code, Codex, OpenCode, Amp, pi-agent, Kilo, GitHub Copilot CLI, and Gemini CLI separately with data source namespaces:
111113

112114
```json
113115
// ~/.config/claude/ccusage.json

‎docs/guide/environment-variables.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ ccusage detects supported data source files from conventional locations by defau
1313
| `OPENCODE_DATA_DIR` | OpenCode | `~/.local/share/opencode` |
1414
| `AMP_DATA_DIR` | Amp | `~/.local/share/amp` |
1515
| `PI_AGENT_DIR` | pi-agent | `~/.pi/agent/sessions` |
16+
| `KILO_DATA_DIR` | Kilo | `~/.local/share/kilo` |
1617
| `COPILOT_OTEL_FILE_EXPORTER_PATH` | Copilot CLI | Explicit `.jsonl` file |
1718
| `GEMINI_DATA_DIR` | Gemini CLI | `~/.gemini/tmp` |
1819

@@ -23,6 +24,7 @@ export CODEX_HOME="/path/to/codex,/archive/codex,/path/to/codex-exec-jsonl"
2324
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
2425
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
2526
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
27+
export KILO_DATA_DIR="/path/to/kilo,/archive/kilo"
2628
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
2729
export GEMINI_DATA_DIR="/path/to/gemini/tmp,/archive/gemini/tmp"
2830
ccusage daily
@@ -194,7 +196,7 @@ To see which environment variables are being used:
194196

195197
```bash
196198
# Show all environment variables
197-
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|PI_AGENT|COPILOT|GEMINI|CCUSAGE|LOG_LEVEL"
199+
env | grep -E "CLAUDE|CODEX|OPENCODE|AMP|PI_AGENT|KILO|COPILOT|GEMINI|CCUSAGE|LOG_LEVEL"
198200

199201
# Debug mode shows environment variable usage
200202
LOG_LEVEL=4 ccusage daily --debug

‎docs/guide/getting-started.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ ccusage codex daily
4949
ccusage opencode weekly
5050
ccusage amp session
5151
ccusage pi monthly
52+
ccusage kilo daily
5253
```
5354

5455
## Your First Report
@@ -165,6 +166,7 @@ If ccusage shows no data, check:
165166
- Amp: `${AMP_DATA_DIR:-~/.local/share/amp}`
166167
- pi-agent: `${PI_AGENT_DIR:-~/.pi/agent/sessions}`
167168
- GitHub Copilot CLI: `~/.copilot/otel/*.jsonl` or `COPILOT_OTEL_FILE_EXPORTER_PATH`
169+
- Kilo: `${KILO_DATA_DIR:-~/.local/share/kilo}`
168170

169171
### Custom Data Directory
170172

@@ -177,6 +179,7 @@ export OPENCODE_DATA_DIR="/path/to/opencode"
177179
export AMP_DATA_DIR="/path/to/amp"
178180
export PI_AGENT_DIR="/path/to/pi/sessions"
179181
export COPILOT_OTEL_FILE_EXPORTER_PATH="/path/to/copilot-otel.jsonl"
182+
export KILO_DATA_DIR="/path/to/kilo"
180183
```
181184

182185
Each source-specific path variable can also contain comma-separated directories:
@@ -186,6 +189,7 @@ export CODEX_HOME="/path/to/codex,/archive/codex,/path/to/codex-exec-jsonl"
186189
export OPENCODE_DATA_DIR="/path/to/opencode,/archive/opencode"
187190
export AMP_DATA_DIR="/path/to/amp,/archive/amp"
188191
export PI_AGENT_DIR="/path/to/pi/sessions,/archive/pi/sessions"
192+
export KILO_DATA_DIR="/path/to/kilo,/archive/kilo"
189193
```
190194

191195
## Getting Help

0 commit comments

Comments
 (0)