ryoppippi
diff --git a/‎.agents/skills/ccusage-agent-sources/SKILL.md‎
Lines changed: 37 additions & 0 deletions b/‎.agents/skills/ccusage-agent-sources/SKILL.md‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎.agents/skills/ccusage-testing/SKILL.md‎
Lines changed: 5 additions & 0 deletions b/‎.agents/skills/ccusage-testing/SKILL.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎.agents/skills/pr-ai-review-workflow/SKILL.md‎
Lines changed: 2 additions & 0 deletions b/‎.agents/skills/pr-ai-review-workflow/SKILL.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎.agents/skills/typescript-style/SKILL.md‎
Lines changed: 19 additions & 0 deletions b/‎.agents/skills/typescript-style/SKILL.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎.agents/skills/use-gunshi-cli/SKILL.md‎
Lines changed: 19 additions & 0 deletions b/‎.agents/skills/use-gunshi-cli/SKILL.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎.github/workflows/ccusage-perf.yaml‎
Lines changed: 3 additions & 0 deletions b/‎.github/workflows/ccusage-perf.yaml‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎apps/amp/CLAUDE.md‎
Lines changed: 0 additions & 16 deletions b/‎apps/amp/CLAUDE.md‎
Lines changed: 0 additions & 16 deletions
diff --git a/‎apps/amp/README.md‎
Lines changed: 18 additions & 0 deletions b/‎apps/amp/README.md‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎apps/amp/eslint.config.js‎
Lines changed: 0 additions & 16 deletions b/‎apps/amp/eslint.config.js‎
Lines changed: 0 additions & 16 deletions
diff --git a/‎apps/amp/index.js‎
Lines changed: 4 additions & 0 deletions b/‎apps/amp/index.js‎
Lines changed: 4 additions & 0 deletions
@@ -48,3 +48,40 @@ Read only the relevant reference before changing parser behavior, token mappings
 - Keep command names and flag semantics aligned unless the source data forces a difference.
 - Internal workspace runtime libraries for bundled/private agent apps belong in `devDependencies`.
 - Deprecated wrapper packages must keep install-time runtime dependencies such as `ccusage` in `dependencies`.
+
+## Adapter Layout
+
+New or migrated agent implementations belong under `apps/ccusage/src/adapter/<agent>/`.
+Keep agent-specific code there, not in deprecated wrapper packages. Split files by responsibility when the implementation grows:
+
+- `index.ts` - thin public adapter surface: `detect<Agent>()`, `load<Agent>Rows()`, and high-level wiring.
+- `paths.ts` - environment variables, default directories, and path discovery.
+- `parser.ts` or `loader.ts` - raw log file discovery and parsing.
+- `schema.ts` - validation schemas and small normalization helpers.
+- `pricing.ts` or `pricing-macro.ts` - agent-specific pricing candidates, bundled pricing, or provider filters.
+- `types.ts` - source-local types when they are not shared outside the adapter.
+
+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.
+
+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.
+
+Treat "same foundation as Claude" as more than shared file walking. JSONL adapters should use the shared byte marker scanner (`processJSONLFileByMarkers()`) when stable row markers exist, and high-volume worker paths should avoid returning large object arrays when typed-array transfer payloads or worker-side aggregation can preserve the same output.
+
+When several adapters expose the same raw-log shape, prefer a small helper such as `defineAgentLogLoader()` over duplicating period/session aggregation. Keep highly specialized loaders such as Codex worker parsing separate when their file format or pricing semantics require it.
+
+Before adding or changing an adapter, read `apps/ccusage/src/adapter/ARCHITECTURE.md` and keep the implementation aligned with its detect, load, parse, aggregate, and parent-return layers.
+
+## Adapter Migration Checklist
+
+For each migrated or new agent:
+
+- Put all source-specific runtime logic under `apps/ccusage/src/adapter/<agent>/`.
+- Keep deprecated wrapper packages as thin compatibility commands only.
+- Implement fast detection that short-circuits once a usable source file is found.
+- Use shared file walking, JSONL byte marker scanning where applicable, worker gating, logging, pricing fetcher lifecycle, date formatting, table rendering, and all-agent aggregation.
+- Keep adapter code responsible for source paths, raw parsing, token mapping, model mapping, source metadata, and agent-specific pricing.
+- Add fixture-backed tests for path discovery, parser behavior, aggregation totals, and important legacy compatibility.
+- Add skipped local-data smoke tests when real user log directories are useful for catching schema drift.
+- Add or update CLI JSON assertions and table snapshots for affected report modes.
+- Validate terminal output with `cmux-debug` when changing table layout, progress, spinners, or responsive behavior.
+- Benchmark affected agents against main or the previous tag, and record whether JSON output still matches for the comparison window.
@@ -14,7 +14,12 @@ Use the `tdd` skill for logic changes and general test readability rules, includ
 - Do not import Vitest globals.
 - Do not use `await import()` or other dynamic imports anywhere, especially in tests.
 - Use `fs-fixture` with `createFixture()` for simulated agent data directories; read the `fs-fixture` skill for API details and README location.
+- Top-level `fs-fixture` imports in implementation files with in-source tests are allowed and preferred over dynamic imports.
 - Use `vi.stubEnv()` instead of mutating `process.env` directly.
+- Prefer testing parser, path resolution, loading, aggregation, pricing, and CLI output behavior over schema-shape tests. Valibot schema declarations usually do not need direct tests unless there is non-trivial normalization logic around them.
+- If schema validation is already exercised through parser or loader tests with realistic log files, do not add separate schema-only tests. Add schema-adjacent tests only when the behavior is not visible through the public loader contract, such as legacy field compatibility or important invalid-record filtering.
+- Path discovery helpers such as `getCodexSessionsPath()` or `getPiAgentPaths()` are real logic. Test explicit path arguments, environment variable paths with `vi.stubEnv()`, missing directories, and default-path fallback when feasible.
+- It is acceptable to add explicitly skipped local-data smoke tests such as `it.skipIf(!hasLocalData)(...)` for real user log directories. These must not fail on clean CI machines.
 
 Utility functions should include concise JSDoc describing their purpose and focused in-source tests for their behavior.
 
 
@@ -37,6 +37,8 @@ For actionable feedback:
 4. Push normally with `git push`.
 5. Reply to the specific comment with what changed and which validation passed.
 
+When replying to AI reviewer inline comments, explicitly mention the reviewer bot in the reply body so the bot treats the message as directed at it rather than ordinary human discussion. Use `@coderabbitai` for CodeRabbit replies. For Cubic, use the current Cubic bot handle shown on the PR/check or recent comments, and mention it at the start of the reply.
+
 Read `references/gh-review-commands.md` for concrete `gh` commands to request review, list comments, reply to inline review comments, add top-level PR comments, update your own comments, and query review threads.
 
 When disagreeing with a review, reply with concrete repository context, not a vague dismissal. If discussion changes the implementation, commit the change and reply again with the result.
 
@@ -62,6 +62,25 @@ Bad:
 import privateApi from 'some-package/private-api';
 ```
 
+## Exhaustive Switches
+
+Use `satisfies never` after switches over discriminated unions or literal unions so new variants fail typecheck until the branch is handled.
+
+Good:
+
+```ts
+switch (agent) {
+	case 'claude':
+		return loadClaude();
+	case 'codex':
+		return loadCodex();
+	default:
+		// exhaustiveness check for new agents added to the union
+		agent satisfies never;
+		throw new Error(`Unsupported agent: ${agent}`);
+}
+```
+
 Good:
 
 ```ts
 
@@ -9,3 +9,22 @@ use gunshi library for creating cli instead of other libraries including cac, ya
 Gunshi is a modern javascript command-line library
 
 For more information, read the gunshi API docs in `node_modules/@gunshi/docs/**.md`.
+
+## Type Inference
+
+Let Gunshi infer command argument values from the concrete `args` object passed to `define()`. Avoid widening command types to `Command<Args>` or `ReturnType<typeof define>` because that erases the specific option keys and value types.
+
+When a command factory needs an explicit return type, preserve the concrete args type:
+
+```ts
+function createCommand(): Command<typeof commandArgs> {
+	return define({
+		args: commandArgs,
+		async run(ctx) {
+			// ctx.values is inferred from commandArgs
+		},
+	});
+}
+```
+
+If a factory chooses between different argument sets, split it into typed helper factories or overloads so each branch keeps `Command<typeof specificArgs>`.
@@ -41,6 +41,7 @@ jobs:
         run: |
           nix develop --command pnpm exec bun apps/ccusage/scripts/generate-large-fixture.ts \
             --output-dir "$RUNNER_TEMP/ccusage-large-fixture" \
+            --codex-output-dir "$RUNNER_TEMP/ccusage-large-codex-fixture" \
             --size-mib 1024
 
       - name: Compare fixture performance
@@ -49,9 +50,11 @@ jobs:
             --base-dir base \
             --head-dir . \
             --fixture-dir apps/ccusage/test/fixtures/claude \
+            --codex-fixture-dir apps/ccusage/test/fixtures/codex \
             --warmup 2 \
             --runs 7 \
             --large-fixture-dir "$RUNNER_TEMP/ccusage-large-fixture" \
+            --large-codex-fixture-dir "$RUNNER_TEMP/ccusage-large-codex-fixture" \
             --large-warmup 0 \
             --large-runs 1 \
             --output "$RUNNER_TEMP/ccusage-perf-comment.md"
 
@@ -0,0 +1,18 @@
+<div align="center">
+    <img src="https://cdn.jsdelivr.net/gh/ryoppippi/ccusage@main/docs/public/logo.svg" alt="ccusage logo" width="256" height="256">
+    <h1>@ccusage/amp</h1>
+</div>
+
+<p align="center">
+    <a href="https://socket.dev/api/npm/package/@ccusage/amp"><img src="https://socket.dev/api/badge/npm/package/@ccusage/amp" alt="Socket Badge" /></a>
+    <a href="https://npmjs.com/package/@ccusage/amp"><img src="https://img.shields.io/npm/v/@ccusage/amp?color=yellow" alt="npm version" /></a>
+    <a href="https://tanstack.com/stats/npm?packageGroups=%5B%7B%22packages%22:%5B%7B%22name%22:%22@ccusage/amp%22%7D%5D%7D%5D&range=30-days&transform=none&binType=daily&showDataMode=all&height=400"><img src="https://img.shields.io/npm/dt/@ccusage/amp" alt="NPM Downloads" /></a>
+    <a href="https://packagephobia.com/result?p=@ccusage/amp"><img src="https://packagephobia.com/badge?p=@ccusage/amp" alt="install size" /></a>
+    <a href="https://deepwiki.com/ryoppippi/ccusage"><img src="https://img.shields.io/badge/DeepWiki-ryoppippi%2Fccusage-blue.svg" alt="DeepWiki"></a>
+</p>
+
+> Deprecated! Use `bunx ccusage` instead.
+
+```bash
+bunx ccusage amp
+```
@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+console.error('use npx ccusage instead');
+process.exitCode = 1;