|
1 | | -# CLAUDE.md - OpenCode Package |
| 1 | +# OpenCode CLI Notes |
2 | 2 |
|
3 | | -This package provides usage analysis for OpenCode, following the same patterns as the codex package. |
| 3 | +## Log Sources |
4 | 4 |
|
5 | | -## Package Overview |
| 5 | +- OpenCode session usage is recorded under `${OPENCODE_DATA_DIR:-~/.local/share/opencode}/storage/message/` (the CLI resolves `OPENCODE_DATA_DIR` and falls back to `~/.local/share/opencode`). |
| 6 | +- Each message is stored as an individual JSON file (not JSONL like Claude or Codex). |
| 7 | +- Message structure includes `tokens.input`, `tokens.output`, `tokens.cache.read`, and `tokens.cache.write`. |
6 | 8 |
|
7 | | -**Name**: `@ccusage/opencode` |
8 | | -**Description**: Usage analysis tool for OpenCode sessions |
9 | | -**Type**: CLI tool (bundled) |
| 9 | +## Token Fields |
10 | 10 |
|
11 | | -## Development Commands |
| 11 | +- `input`: total input tokens sent to the model. |
| 12 | +- `output`: output tokens (completion text). |
| 13 | +- `cache.read`: cached portion of the input (prompt-caching). |
| 14 | +- `cache.write`: cache creation tokens. |
| 15 | +- Pre-calculated `cost` field may be present in OpenCode messages. |
12 | 16 |
|
13 | | -**Testing and Quality:** |
| 17 | +## Cost Calculation |
14 | 18 |
|
15 | | -- `pnpm run test` - Run all tests with vitest |
16 | | -- `pnpm run lint` - Lint code using ESLint |
17 | | -- `pnpm run format` - Format and auto-fix code with ESLint |
18 | | -- `pnpm typecheck` - Type check with TypeScript |
| 19 | +- OpenCode messages may include pre-calculated `cost` field in USD. |
| 20 | +- When `cost` is not present, costs should be calculated using model pricing data. |
| 21 | +- Token mapping: |
| 22 | + - `inputTokens` ← `tokens.input` |
| 23 | + - `outputTokens` ← `tokens.output` |
| 24 | + - `cacheReadInputTokens` ← `tokens.cache.read` |
| 25 | + - `cacheCreationInputTokens` ← `tokens.cache.write` |
19 | 26 |
|
20 | | -**Build and Release:** |
| 27 | +## CLI Usage |
21 | 28 |
|
22 | | -- `pnpm run build` - Build distribution files with tsdown |
23 | | -- `pnpm run prerelease` - Full release workflow (lint + typecheck + build) |
| 29 | +- Treat OpenCode as a sibling to `apps/ccusage` and `apps/codex`. |
| 30 | +- Reuse shared packages (`@ccusage/terminal`, `@ccusage/internal`) wherever possible. |
| 31 | +- OpenCode is packaged as a bundled CLI. Keep every runtime dependency in `devDependencies`. |
| 32 | +- Entry point uses Gunshi framework. |
| 33 | +- Data discovery relies on `OPENCODE_DATA_DIR` environment variable. |
| 34 | +- Default path: `~/.local/share/opencode`. |
24 | 35 |
|
25 | | -**Development Usage:** |
| 36 | +## Testing Notes |
26 | 37 |
|
27 | | -- `pnpm run start daily` - Show daily usage report |
28 | | -- Add `--json` flag for JSON output format |
29 | | - |
30 | | -## Architecture |
31 | | - |
32 | | -This package mirrors the codex package structure: |
33 | | - |
34 | | -**Key Modules:** |
35 | | - |
36 | | -- `src/data-loader.ts` - Loads OpenCode message JSON files |
37 | | -- `src/commands/daily.ts` - Daily usage reports |
38 | | -- `src/commands/index.ts` - Command exports |
39 | | - |
40 | | -**Data Flow:** |
41 | | - |
42 | | -1. Loads JSON files from `~/.local/share/opencode/storage/message/` |
43 | | -2. Converts to common `LoadedUsageEntry` format |
44 | | -3. Aggregates by date |
45 | | -4. Outputs formatted tables or JSON |
46 | | - |
47 | | -## Testing Guidelines |
48 | | - |
49 | | -- **In-Source Testing**: Tests written in same files using `if (import.meta.vitest != null)` blocks |
50 | | -- **Vitest Globals Enabled**: Use `describe`, `it`, `expect` directly without imports |
51 | | -- **Mock Data**: Uses `fs-fixture` with `using` for test data |
52 | | -- **CRITICAL**: NEVER use `await import()` dynamic imports anywhere |
53 | | - |
54 | | -## Code Style |
55 | | - |
56 | | -- **Error Handling**: Skip malformed files silently, no Result type needed for simple cases |
57 | | -- **Imports**: Use workspace packages (`@ccusage/terminal`, `@ccusage/internal`) |
58 | | -- **Dependencies**: All runtime deps in `devDependencies` (bundled CLI) |
59 | | - |
60 | | -## Environment Variables |
61 | | - |
62 | | -- `OPENCODE_DATA_DIR` - Custom OpenCode data directory path (defaults to `~/.local/share/opencode`) |
63 | | - |
64 | | -## Package Exports |
65 | | - |
66 | | -Minimal exports for CLI usage - primarily the command interface through gunshi. |
| 38 | +- Tests rely on `fs-fixture` with `using` to ensure cleanup. |
| 39 | +- All vitest blocks live alongside implementation files via `if (import.meta.vitest != null)`. |
| 40 | +- Vitest globals are enabled - use `describe`, `it`, `expect` directly without imports. |
0 commit comments