Skip to content

Commit d164e46

Browse files
committed
feat(hermes): port usage adapter to Rust
Merge the current main Rust CLI migration into the Hermes Agent PR and replace the old TypeScript Hermes adapter with a Rust implementation. The Rust adapter discovers state.db from HERMES_HOME or ~/.hermes, reads session rows read-only from SQLite, preserves recorded message counts and costs, and includes reasoning tokens in total-token accounting and output-side cost calculation. Also wires Hermes into direct reports, all-agent reports, progress labels, config schema, CLI parsing, README, and docs.
2 parents 3cae87c + 7971969 commit d164e46

221 files changed

Lines changed: 21551 additions & 31991 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/ast-grep/SKILL.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
name: ast-grep
3+
description: Guides ccusage structural code searches with ast-grep. Use when finding syntax patterns, validating migrations, or writing AST-based search commands.
4+
---
5+
6+
# ast-grep
7+
8+
Use ast-grep when a search needs syntax structure rather than plain text. Prefer `rg` for simple text search.
9+
10+
## Tooling
11+
12+
This repo provides `ast-grep` through `flake.nix`. Run commands from the Nix dev shell, or use `direnv exec .` when the shell is not already active:
13+
14+
```sh
15+
direnv exec . ast-grep run --lang ts --pattern '/$P/' --json=stream apps packages
16+
```
17+
18+
If `direnv` is unavailable and this is a one-off search, use comma as a fallback:
19+
20+
```sh
21+
, ast-grep run --lang ts --pattern '/$P/' --json=stream apps packages
22+
```
23+
24+
## Workflow
25+
26+
1. Describe the syntax shape you need to find.
27+
2. Start with a small pattern and test it against the repo.
28+
3. Use `--debug-query` when the pattern does not match the AST shape you expected.
29+
4. Only move to YAML rules when `run --pattern` cannot express the search.
30+
31+
## Commands
32+
33+
For quick pattern searches:
34+
35+
```sh
36+
ast-grep run --lang ts --pattern 'console.log($ARG)' apps packages
37+
```
38+
39+
For JSON output that scripts can consume:
40+
41+
```sh
42+
ast-grep run --lang ts --pattern '/$P/' --json=stream apps packages
43+
```
44+
45+
## Rule Tips
46+
47+
- Use `run --pattern` for simple single-node matches.
48+
- Use `scan --rule` or `scan --inline-rules` for relational rules such as `inside` or `has`.
49+
- Add `stopBy: end` to relational rules so ast-grep searches the full direction.
50+
- Use `--debug-query=ast`, `--debug-query=cst`, or `--debug-query=pattern` when a rule does not match the code shape you expected.

‎.agents/skills/bun-api-reference/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: bun-api-reference
3-
description: Check local Bun runtime API documentation and types from node_modules/bun-types before using or changing Bun APIs such as Bun.$, Bun.file(), Bun.write(), Bun.spawn(), Bun.argv, Bun.deepEquals(), Bun.stdout, Bun.stderr, and Bun.stringWidth().
3+
description: Checks local bun-types documentation before using or changing Bun runtime APIs such as Bun.$, files, spawning, argv, stdout, stderr, and string width.
44
---
55

66
# Bun API Reference

‎.agents/skills/bun-cpu-profile/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: bun-cpu-profile
3-
description: Debug Bun CPU performance for TypeScript/JavaScript CLIs and scripts with Bun CPU profiles, markdown profiles, hyperfine comparisons, and git worktree A/B runs. Use when investigating slow Bun execution, validating performance optimizations, comparing a branch against main, or interpreting .cpuprofile / --cpu-prof-md output.
3+
description: Profiles Bun TypeScript and JavaScript CLI CPU performance. Use when debugging slow execution, reading CPU profiles, or comparing branch speed with hyperfine.
44
---
55

66
# Bun CPU Profile

‎.agents/skills/ccusage-agent-sources/SKILL.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: ccusage-agent-sources
3-
description: Implement or debug ccusage parsers and reports for Claude Code, Codex, OpenCode, Amp, and pi-agent usage data, including log locations, token field mappings, pricing rules, CLI flags, and package-specific behavior.
3+
description: Guides ccusage agent source work for Claude Code, Codex, OpenCode, Amp, and pi-agent parsers, log paths, token mappings, costs, and reports.
44
---
55

66
# ccusage Agent Sources
@@ -60,6 +60,8 @@ Keep agent-specific code there. Split files by responsibility when the implement
6060
- `pricing.ts` or `pricing-macro.ts` - agent-specific pricing candidates, bundled pricing, or provider filters.
6161
- `types.ts` - source-local types when they are not shared outside the adapter.
6262

63+
For Rust work, use the `ccusage-rust` skill and mirror the same responsibility boundaries under `rust/crates/ccusage/src/adapter/<agent>/` where practical: `mod.rs`, `paths.rs`, `parser.rs`, `loader.rs`, and `report.rs`.
64+
6365
When moving an existing loader into an adapter, update internal imports to the adapter path instead of adding compatibility re-export shims. Keep old root-level modules only when they are part of the package's declared public exports or are dedicated bundled worker entries. In `apps/ccusage`, `src/data-loader.ts` is a worker/build entry for the optimized Claude `data-loader` chunk from PR #984; do not put new source logic there.
6466

6567
Use shared ccusage foundation for rendering, table layout, logging, date formatting, progress, pricing fetcher lifecycle, JSONL walking, worker gating, worker spawn/result ordering, and aggregation wherever the source data permits. Agent adapters should mainly own source-specific log discovery, parsing, token mapping, model mapping, and source-specific metadata.
@@ -82,6 +84,7 @@ For each migrated or new agent:
8284
- Add fixture-backed tests for path discovery, parser behavior, aggregation totals, and important legacy compatibility.
8385
- Add skipped local-data smoke tests when real user log directories are useful for catching schema drift.
8486
- Add or update CLI JSON assertions and table snapshots for affected report modes.
85-
- Add or update user-facing docs under `docs/guide/`, including VitePress navigation when a new agent guide is introduced. Use the `ccusage-docs` skill for docs conventions.
87+
- Audit every user-facing entrypoint that lists supported agents, commands, options, report modes, or examples. Update the root `README.md`, `apps/ccusage/README.md`, `docs/guide/`, and VitePress navigation when the adapter changes what users can run or discover. Use the `ccusage-docs` skill for docs conventions.
88+
- When adding a new agent guide, include README usage examples, docs guide content, related guide links, and VitePress navigation in the same change unless the user explicitly scopes documentation out.
8689
- Validate terminal output with `cmux-debug` when changing table layout, progress, spinners, or responsive behavior.
8790
- Benchmark affected agents against main or the previous tag, and record whether JSON output still matches for the comparison window.

‎.agents/skills/ccusage-development/SKILL.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: ccusage-development
3-
description: Work in the ccusage monorepo with its unified ccusage command surface, bundled CLI packaging, pnpm commands, TypeScript style, exports, dependencies, and post-change validation workflow. Use when editing packages under apps/, packages/, docs/, or shared repository configuration.
3+
description: Guides ccusage monorepo development. Use when editing packages, docs, shared configuration, bundled CLI packaging, dependencies, exports, or validation commands.
44
---
55

66
# ccusage Development
@@ -48,6 +48,7 @@ Tools are managed by `flake.nix` and `package.json`. Use `comma` or `nix run` fo
4848

4949
- Use TypeScript strict-mode patterns already present in the package.
5050
- Prefer `satisfies` and `as const satisfies` over unsafe `as` assertions; use the `typescript-style` skill for details.
51+
- Use the `ccusage-rust` skill before editing `rust/crates/**`, native packaging behavior, Rust pricing embedding, or Rust performance work.
5152
- Use `.ts` extensions for local imports.
5253
- Use Node path utilities for file paths.
5354
- Use `logger.ts` instead of `console.log`.

‎.agents/skills/ccusage-docs/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: ccusage-docs
3-
description: Edit the ccusage VitePress documentation with screenshot placement, accessibility, schema-copy build behavior, markdown linting, and guide organization conventions. Use when working under docs/ or adding user-facing documentation.
3+
description: Guides ccusage VitePress documentation work. Use when editing docs, screenshots, accessibility, schema-copy behavior, markdown linting, or user-facing guides.
44
---
55

66
# ccusage Docs
@@ -21,12 +21,14 @@ The docs build copies `apps/ccusage/config-schema.json` to `docs/public/config-s
2121

2222
## Structure
2323

24+
- `README.md` and `apps/ccusage/README.md` - package entrypoints for supported sources, common commands, features, and installation examples
2425
- `docs/guide/` - user guides and tutorials
2526
- `docs/public/` - screenshots, static assets, and generated config schema
2627
- `docs/.vitepress/` - VitePress configuration and theme customization
2728

2829
## Content Rules
2930

31+
- When adding or changing a user-facing agent, command, option, report mode, or example, audit and update the root `README.md`, `apps/ccusage/README.md`, relevant `docs/guide/` pages, related cross-links, and VitePress navigation before finishing.
3032
- Prefer the unified command form in new or edited docs: `ccusage codex ...`, `ccusage opencode ...`, `ccusage amp ...`, and `ccusage pi ...`.
3133
- Standalone wrapper commands such as `ccusage-codex`, `ccusage-opencode`, `ccusage-amp`, and `ccusage-pi` have been removed. Do not promote or reintroduce them in docs.
3234
- Place screenshots immediately after the page H1 when a guide has a primary screenshot.
Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
name: ccusage-rust
3+
description: Guides ccusage Rust implementation work. Use when editing rust/crates, native packaging, Rust performance, parser/module layout, pricing embedding, or Rust/TypeScript parity.
4+
paths:
5+
- 'rust/**/*.rs'
6+
- 'rust/**/*.toml'
7+
- 'rust/**/build.rs'
8+
globs: 'rust/**/*.rs,rust/**/*.toml,rust/**/build.rs'
9+
---
10+
11+
# ccusage Rust
12+
13+
Use this skill for the native Rust CLI under `rust/crates/ccusage` and `rust/crates/ccusage-terminal`.
14+
15+
## Source Parity
16+
17+
Rust must match the TypeScript implementation on `origin/main` unless the user explicitly scopes a behavior change. Before implementing or refactoring an agent, inspect the corresponding TypeScript adapter:
18+
19+
```sh
20+
git ls-tree -r --name-only origin/main apps/ccusage/src/adapter
21+
git show origin/main:apps/ccusage/src/adapter/<agent>/index.ts
22+
git show origin/main:apps/ccusage/src/adapter/<agent>/parser.ts
23+
git show origin/main:apps/ccusage/src/adapter/<agent>/paths.ts
24+
```
25+
26+
Preserve report semantics, JSON fields, table columns, progress/spinner text, agent grouping, date filtering, `--offline`, `CLAUDE_CONFIG_DIR`, and source-specific environment variables.
27+
28+
## Module Layout
29+
30+
Do not keep growing `main.rs` or single large adapter files. Mirror the TypeScript responsibility boundaries where practical:
31+
32+
- `adapter/<agent>/mod.rs` - public adapter surface and command wiring.
33+
- `adapter/<agent>/paths.rs` - environment variables, defaults, and path discovery.
34+
- `adapter/<agent>/parser.rs` - raw record parsing and token/model mapping.
35+
- `adapter/<agent>/loader.rs` - file walking, SQLite reads, dedupe, and date filtering entry points.
36+
- `adapter/<agent>/report.rs` - JSON/table row shaping when agent-specific.
37+
- shared modules stay in `types.rs`, `summary.rs`, `output.rs`, `pricing.rs`, `progress.rs`, and `date_utils.rs`.
38+
39+
Keep public `pub(crate)` surfaces narrow. Prefer moving tests with the code they exercise instead of leaving all Rust tests in `main.rs`.
40+
41+
When splitting large Rust modules or removing duplication, use the `reduce-similarities` skill, which runs `similarity-rs` for `.rs` files.
42+
43+
## Pricing Embedding
44+
45+
TypeScript uses build/macro-time pricing snapshots. Rust should not rely on a manually edited `claude-pricing.json` as the only embedded source.
46+
47+
When changing pricing:
48+
49+
- Prefer a `build.rs` step that fetches LiteLLM `model_prices_and_context_window.json` into `OUT_DIR`.
50+
- Keep a checked-in fallback snapshot so offline builds and network failures still work.
51+
- Load the generated build-time snapshot first, then fallback pricing, then runtime fetch when not `--offline`.
52+
- Add tests for embedded/offline pricing and context limits.
53+
54+
## Performance
55+
56+
Read the local Rust Performance Book clone before non-trivial optimization:
57+
58+
```text
59+
/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/profiling.md
60+
/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/io.md
61+
/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/heap-allocations.md
62+
/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/parallelism.md
63+
/Users/ryoppippi/ghq/github.com/nnethercote/perf-book/src/type-sizes.md
64+
```
65+
66+
Profile before committing an optimization. Validate with end-to-end `hyperfine` and JSON/table parity, not only microbenchmarks.
67+
68+
For ccusage workloads, check:
69+
70+
- I/O count and buffering before CPU-only tweaks.
71+
- Avoid unnecessary `String` allocation and cloning on hot paths; prefer borrowed `&str`, `Arc<str>`, or typed summaries where ownership is needed.
72+
- Avoid returning large intermediate object vectors when worker-side aggregation or typed transfer payloads can preserve output.
73+
- Use parallelism only when it improves end-to-end command time on real fixture shapes.
74+
- Keep binary size visible when adding dependencies or enabling features.
75+
76+
## Validation
77+
78+
Use the `ccusage-testing` skill for Rust test commands. For perf or parity work, compare against `origin/main` TypeScript output for a stable fixture window before changing behavior.

‎.agents/skills/ccusage-testing/SKILL.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,32 @@
11
---
22
name: ccusage-testing
3-
description: Write or update ccusage tests using in-source Vitest blocks, fs-fixture data, snapshots for CLI table output, Claude model pricing expectations, and LiteLLM compatibility. Use when adding tests, fixing test failures, or changing usage aggregation and cost behavior.
3+
description: Guides ccusage tests. Use when adding or fixing in-source Vitest, Rust cargo tests, fs-fixture data, CLI snapshots, Claude model pricing, or LiteLLM compatibility.
44
---
55

66
# ccusage Testing
77

88
Use the `tdd` skill for logic changes and general test readability rules, including the guidance to avoid over-DRYing tests when duplication improves clarity. Use the `fs-fixture` skill when creating filesystem fixtures. This skill adds ccusage-specific Vitest, fixture, model, and pricing rules.
99

10+
## Rust Tests
11+
12+
Use `direnv exec .` when the current shell does not already expose the Rust toolchain:
13+
14+
```sh
15+
direnv exec . cargo test --manifest-path rust/Cargo.toml --workspace
16+
direnv exec . cargo test --manifest-path rust/Cargo.toml --workspace <test_name>
17+
direnv exec . cargo test --manifest-path rust/Cargo.toml --workspace -- --ignored
18+
```
19+
20+
For repo-wide validation, prefer the package script because it runs Vitest and Rust tests together:
21+
22+
```sh
23+
direnv exec . pnpm run test
24+
```
25+
26+
Put Rust unit tests near the module they exercise with `#[cfg(test)] mod tests`. When splitting a large module, move its tests with the code instead of leaving unrelated tests in `main.rs`.
27+
28+
Use fixture-backed Rust tests for parser, path discovery, SQLite loading, dedupe, aggregation, pricing, and CLI output parity. For TDD syntax and focused cargo test examples, read `../tdd/references/rust-examples.md`.
29+
1030
## Vitest Pattern
1131

1232
- Tests live beside implementation in `if (import.meta.vitest != null)` blocks.
@@ -27,7 +47,8 @@ Utility functions should include concise JSDoc describing their purpose and focu
2747

2848
- Avoid `try`/`catch` in tests for expected failures. Use `expect(...).toThrow()`, `await expect(...).rejects`, or explicit Result failure assertions.
2949
- Avoid `if` branches inside test bodies. Split behaviors into separate tests or use `it.each` for table-driven cases.
30-
- Do not over-DRY tests. Keep repeated setup inline when it makes the behavior easier to read.
50+
- Tests do not need to be DRY. Prefer repeated, explicit setup in each test when it makes the behavior easier to read.
51+
- Do not hoist one-off values out of tests. Write literals and direct setup values inline in the test body when sharing them would make the behavior harder to read.
3152

3253
For concrete good and bad examples, read `../tdd/references/vitest-examples.md`.
3354

‎.agents/skills/cmux-debug/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: cmux-debug
3-
description: Use cmux to run commands in an existing terminal surface, capture rendered output, inspect terminal geometry, and debug CLI visual regressions. Use when validating terminal UIs, responsive tables, long-running CLI commands, or pane output in cmux.
3+
description: Guides cmux terminal debugging. Use when validating CLI visual output, responsive tables, terminal geometry, long-running commands, or pane captures.
44
---
55

66
# cmux Debug

‎.agents/skills/commit/SKILL.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: commit
3-
description: Creates atomic git commits following Conventional Commits specification with detailed, well-structured messages. Analyzes changes and splits them into logical units. Use when committing code changes that need proper structure and comprehensive documentation (e.g., "commit my authentication changes" or "finished implementing search, time to commit").
3+
description: Creates atomic Conventional Commits. Use when committing code changes, splitting hunks into revertable units, or writing detailed commit messages.
44
---
55

66
<!--
@@ -77,6 +77,15 @@ Use standard git history commands to understand intent before committing. Prefer
7777
- Potential impacts
7878
- Wrap at 72 characters
7979

80+
**Subject should name the artifact or behavior changed**:
81+
82+
- Prefer concrete subjects that make sense when read alone in a commit list.
83+
- Avoid vague review-process subjects such as `chore: address review feedback`,
84+
`chore: apply comments`, or `fix: update per CodeRabbit`.
85+
- Put reviewer context in the body, not the subject. For example, use
86+
`docs(skills): clarify arkregex newline guidance` with a body explaining that
87+
it addresses CodeRabbit feedback.
88+
8089
## Quality Checks
8190

8291
- Can this be reverted without breaking other functionality?

0 commit comments

Comments
 (0)