feat(cli): add --client/-c filter flag, deprecate per-client booleans

README.ja.md

@@ -284,64 +284,31 @@ TUIで`g`を押すか、`--light`/`--json`モードで`--group-by`を使用し
 
 ### プラットフォーム別フィルタリング
 
+`--client`（短縮形 `-c`）でレポートを 1 つ以上のクライアントに絞り込めます。フラグは繰り返し可能で、カンマ区切りの値にも対応し、すべてのレポートコマンドで利用できます：
+
 ```bash
 # OpenCodeの使用量のみ表示
-tokscale --opencode
-
-# Claude Codeの使用量のみ表示
-tokscale --claude
-
-# Codex CLIの使用量のみ表示
-tokscale --codex
-
-# OpenClawの使用量のみ表示
-tokscale --openclaw
-
-# Piの使用量のみ表示
-tokscale --pi
-
-# Gemini CLIの使用量のみ表示
-tokscale --gemini
-
-# Cursor IDEの使用量のみ表示（事前に`tokscale cursor login`が必要）
-tokscale --cursor
+tokscale --client opencode
 
-# Ampの使用量のみ表示
-tokscale --amp
+# カンマ区切り：複数のクライアントを同時にフィルター
+tokscale --client opencode,claude
 
-# Droidの使用量のみ表示
-tokscale --droid
+# 繰り返し：同じ効果（シェルエイリアスと相性が良い）
+tokscale -c opencode -c claude
 
-# Hermes Agentの使用量のみ表示
-tokscale --hermes
+# Cursor IDE は事前に `tokscale cursor login` が必要
+tokscale --client cursor
 
-# Kimi CLIの使用量のみ表示
-tokscale --kimi
+# Synthetic（synthetic.new）は他のエージェントセッションから検出されます
+tokscale --client synthetic
 
-# Qwen CLIの使用量のみ表示
-tokscale --qwen
-
-# Roo Codeの使用量のみ表示
-tokscale --roocode
-
-# Kiloの使用量のみ表示
-tokscale --kilocode
-
-# Muxの使用量のみ表示
-tokscale --mux
-
-# Kilo CLIの使用量のみ表示
-tokscale --kilo
-
-# Crushの使用量のみ表示
-tokscale --crush
+# 他のフィルターと組み合わせ
+tokscale --client opencode,claude --week --json
+```
 
-# Synthetic (synthetic.new) の使用量のみ表示
-tokscale --synthetic
+利用可能な値: `opencode`, `claude`, `codex`, `copilot`, `gemini`, `cursor`, `amp`, `droid`, `openclaw`, `hermes`, `pi`, `kimi`, `qwen`, `roocode`, `kilocode`, `kilo`, `mux`, `crush`, `synthetic`。
 
-# フィルターを組み合わせ
-tokscale --opencode --claude
-```
+> **非推奨のお知らせ**: 既存の単一クライアントフラグ（`--opencode`、`--claude`、`--codex` など）は後方互換性のため引き続き動作しますが、`--help` から非表示となり、次のメジャーリリースで削除予定です。可能な限り `--client` への移行を推奨します。インタラクティブな端末で旧フラグを使用すると 1 行の警告が表示されます。
 
 ### 日付フィルタリング
 
@@ -360,7 +327,7 @@ tokscale --since 2024-01-01 --until 2024-12-31
 tokscale --year 2024
 
 # 他のオプションと組み合わせ
-tokscale models --week --claude --json
+tokscale models --week --client claude --json
 tokscale monthly --month --benchmark
 ```
 
@@ -420,7 +387,7 @@ tokscale whoami
 tokscale submit
 
 # フィルター付きで送信
-tokscale submit --opencode --claude --since 2024-01-01
+tokscale submit --client opencode,claude --since 2024-01-01
 
 # 送信内容をプレビュー（ドライラン）
 tokscale submit --dry-run
@@ -487,7 +454,8 @@ Tokscaleは設定を`~/.config/tokscale/settings.json`に保存します：
 ```json
 {
   "colorPalette": "blue",
-  "includeUnusedModels": false
+  "includeUnusedModels": false,
+  "defaultClients": ["opencode", "claude"]
 }
 ```
 
@@ -498,6 +466,7 @@ Tokscaleは設定を`~/.config/tokscale/settings.json`に保存します：
 | `autoRefreshEnabled` | boolean | `false` | TUIの自動更新を有効化 |
 | `autoRefreshMs` | number | `60000` | 自動更新間隔（30000-3600000ms） |
 | `nativeTimeoutMs` | number | `300000` | ネイティブサブプロセス処理の最大時間（5000-3600000ms） |
+| `defaultClients` | string[] | `[]` | `--client/-c` フラグを渡さない場合に適用されるクライアントフィルター。`--client` と同じ ID を受け付けます（例: `["opencode", "claude", "synthetic"]`）。未知の ID は無視されます。CLI フラグが指定されるとこのリストは完全に無視されます — マージはしません。 |
 
 ### 環境変数
 
@@ -786,7 +755,7 @@ tokscale graph --since 2024-01-01 --until 2024-12-31
 tokscale graph --year 2024
 
 # プラットフォーム別フィルター
-tokscale graph --opencode --claude
+tokscale graph --client opencode,claude
 
 # 処理時間ベンチマークを表示
 tokscale graph --output data.json --benchmark

README.ko.md

@@ -283,64 +283,31 @@ TUI에서 `g`를 누르거나 `--light`/`--json` 모드에서 `--group-by`를 
 
 ### 플랫폼별 필터링
 
+`--client` (단축형 `-c`) 플래그로 하나 이상의 클라이언트로 리포트 범위를 좁힐 수 있습니다. 반복 사용 가능하며 콤마로 구분된 값도 지원하고, 모든 리포트 명령에서 동작합니다:
+
 ```bash
 # OpenCode 사용량만 표시
-tokscale --opencode
-
-# Claude Code 사용량만 표시
-tokscale --claude
-
-# Codex CLI 사용량만 표시
-tokscale --codex
-
-# OpenClaw 사용량만 표시
-tokscale --openclaw
-
-# Pi 사용량만 표시
-tokscale --pi
-
-# Gemini CLI 사용량만 표시
-tokscale --gemini
-
-# Cursor IDE 사용량만 표시 (먼저 `tokscale cursor login` 필요)
-tokscale --cursor
+tokscale --client opencode
 
-# Amp 사용량만 표시
-tokscale --amp
+# 콤마로 구분: 여러 클라이언트 동시 필터
+tokscale --client opencode,claude
 
-# Droid 사용량만 표시
-tokscale --droid
+# 반복: 같은 효과 (쉘 alias와 함께 쓰기 좋음)
+tokscale -c opencode -c claude
 
-# Hermes Agent 사용량만 표시
-tokscale --hermes
+# Cursor IDE는 사전에 `tokscale cursor login` 필요
+tokscale --client cursor
 
-# Kimi CLI 사용량만 표시
-tokscale --kimi
+# Synthetic (synthetic.new) 은 다른 에이전트 세션에서 검출됨
+tokscale --client synthetic
 
-# Qwen CLI 사용량만 표시
-tokscale --qwen
-
-# Roo Code 사용량만 표시
-tokscale --roocode
-
-# Kilo 사용량만 표시
-tokscale --kilocode
-
-# Mux 사용량만 표시
-tokscale --mux
-
-# Kilo CLI 사용량만 표시
-tokscale --kilo
-
-# Crush 사용량만 표시
-tokscale --crush
+# 다른 필터와 조합
+tokscale --client opencode,claude --week --json
+```
 
-# Synthetic (synthetic.new) 사용량만 표시
-tokscale --synthetic
+가능한 값: `opencode`, `claude`, `codex`, `copilot`, `gemini`, `cursor`, `amp`, `droid`, `openclaw`, `hermes`, `pi`, `kimi`, `qwen`, `roocode`, `kilocode`, `kilo`, `mux`, `crush`, `synthetic`.
 
-# 필터 조합
-tokscale --opencode --claude
-```
+> **Deprecation 안내**: 기존 단일 클라이언트 플래그 (`--opencode`, `--claude`, `--codex` 등)는 하위 호환성을 위해 여전히 동작하지만 `--help`에서 숨겨졌으며 다음 메이저 릴리스에서 제거됩니다. 가능한 한 `--client`로 마이그레이션하세요. 인터랙티브 터미널에서 레거시 플래그를 사용하면 한 줄 경고가 출력됩니다.
 
 ### 날짜 필터링
 
@@ -359,7 +326,7 @@ tokscale --since 2024-01-01 --until 2024-12-31
 tokscale --year 2024
 
 # 다른 옵션과 조합
-tokscale models --week --claude --json
+tokscale models --week --client claude --json
 tokscale monthly --month --benchmark
 ```
 
@@ -419,7 +386,7 @@ tokscale whoami
 tokscale submit
 
 # 필터와 함께 제출
-tokscale submit --opencode --claude --since 2024-01-01
+tokscale submit --client opencode,claude --since 2024-01-01
 
 # 제출될 내용 미리보기 (드라이 런)
 tokscale submit --dry-run
@@ -486,7 +453,8 @@ Tokscale은 설정을 `~/.config/tokscale/settings.json`에 저장합니다:
 ```json
 {
   "colorPalette": "blue",
-  "includeUnusedModels": false
+  "includeUnusedModels": false,
+  "defaultClients": ["opencode", "claude"]
 }
 ```
 
@@ -497,6 +465,7 @@ Tokscale은 설정을 `~/.config/tokscale/settings.json`에 저장합니다:
 | `autoRefreshEnabled` | boolean | `false` | TUI 자동 새로고침 활성화 |
 | `autoRefreshMs` | number | `60000` | 자동 새로고침 간격 (30000-3600000ms) |
 | `nativeTimeoutMs` | number | `300000` | 네이티브 서브프로세스 처리 최대 시간 (5000-3600000ms) |
+| `defaultClients` | string[] | `[]` | `--client/-c` 플래그를 전달하지 않을 때 적용되는 기본 클라이언트 필터. `--client`와 동일한 ID를 받습니다 (예: `["opencode", "claude", "synthetic"]`). 알 수 없는 ID는 자동으로 무시됩니다. CLI 플래그가 있으면 이 목록은 완전히 무시됩니다 — 병합되지 않습니다. |
 
 ### 환경 변수
 
@@ -785,7 +754,7 @@ tokscale graph --since 2024-01-01 --until 2024-12-31
 tokscale graph --year 2024
 
 # 플랫폼별 필터
-tokscale graph --opencode --claude
+tokscale graph --client opencode,claude
 
 # 처리 시간 벤치마크 표시
 tokscale graph --output data.json --benchmark

README.md

@@ -287,67 +287,31 @@ Press `g` in the TUI or use `--group-by` in `--light`/`--json` mode to control h
 
 ### Filtering by Platform
 
+Use `--client` (short `-c`) to scope reports to one or more clients. The flag is repeatable, accepts comma-separated values, and works with every report command:
+
 ```bash
 # Show only OpenCode usage
-tokscale --opencode
-
-# Show only Claude Code usage
-tokscale --claude
-
-# Show only Codex CLI usage
-tokscale --codex
-
-# Show only Copilot CLI usage
-tokscale --copilot
-
-# Show only OpenClaw usage
-tokscale --openclaw
-
-# Show only Pi usage
-tokscale --pi
-
-# Show only Gemini CLI usage
-tokscale --gemini
-
-# Show only Cursor IDE usage (requires `tokscale cursor login` first)
-tokscale --cursor
+tokscale --client opencode
 
-# Show only Amp usage
-tokscale --amp
+# Comma-separated: combine multiple clients
+tokscale --client opencode,claude
 
-# Show only Droid usage
-tokscale --droid
+# Repeated: same effect, useful with shell aliases
+tokscale -c opencode -c claude
 
-# Show only Hermes Agent usage
-tokscale --hermes
+# Cursor IDE requires `tokscale cursor login` first
+tokscale --client cursor
 
-# Show only Kimi CLI usage
-tokscale --kimi
+# Synthetic (synthetic.new) is detected from other agent sessions
+tokscale --client synthetic
 
-# Show only Qwen CLI usage
-tokscale --qwen
-
-# Show only Roo Code usage
-tokscale --roocode
-
-# Show only Kilo usage
-tokscale --kilocode
-
-# Show only Mux usage
-tokscale --mux
-
-# Show only Kilo CLI usage
-tokscale --kilo
-
-# Show only Crush usage
-tokscale --crush
+# Combine with other filters
+tokscale --client opencode,claude --week --json
+```
 
-# Show only Synthetic (synthetic.new) usage
-tokscale --synthetic
+Possible values: `opencode`, `claude`, `codex`, `copilot`, `gemini`, `cursor`, `amp`, `droid`, `openclaw`, `hermes`, `pi`, `kimi`, `qwen`, `roocode`, `kilocode`, `kilo`, `mux`, `crush`, `synthetic`.
 
-# Combine filters
-tokscale --opencode --claude
-```
+> **Deprecation notice**: The legacy single-client flags (`--opencode`, `--claude`, `--codex`, etc.) still work for backward compatibility but are hidden from `--help` and will be removed in the next major release. Migrate to `--client` whenever possible. Running tokscale in an interactive terminal will print a one-line warning when a legacy flag is used.
 
 ### Date Filtering
 
@@ -366,7 +330,7 @@ tokscale --since 2024-01-01 --until 2024-12-31
 tokscale --year 2024
 
 # Combine with other options
-tokscale models --week --claude --json
+tokscale models --week --client claude --json
 tokscale monthly --month --benchmark
 ```
 
@@ -426,7 +390,7 @@ tokscale whoami
 tokscale submit
 
 # Submit with filters
-tokscale submit --opencode --claude --since 2024-01-01
+tokscale submit --client opencode,claude --since 2024-01-01
 
 # Preview what would be submitted (dry run)
 tokscale submit --dry-run
@@ -494,6 +458,7 @@ Tokscale stores settings in `~/.config/tokscale/settings.json`:
 {
   "colorPalette": "blue",
   "includeUnusedModels": false,
+  "defaultClients": ["opencode", "claude"],
   "scanner": {
     "extraScanPaths": {
       "codex": [
@@ -512,10 +477,13 @@ Tokscale stores settings in `~/.config/tokscale/settings.json`:
 | `autoRefreshEnabled` | boolean | `false` | Enable auto-refresh in TUI |
 | `autoRefreshMs` | number | `60000` | Auto-refresh interval (30000-3600000ms) |
 | `nativeTimeoutMs` | number | `300000` | Maximum time for native subprocess processing (5000-3600000ms) |
+| `defaultClients` | string[] | `[]` | Client filter applied when no `--client/-c` flag is passed. Accepts the same ids as `--client` (e.g. `["opencode", "claude", "synthetic"]`). Unknown ids are silently dropped. CLI flags always override this list completely — no merging. |
 | `scanner.extraScanPaths` | object | `{}` | Additional per-client scan roots for sessions outside Tokscale's default home-root locations |
 
 Use `scanner.extraScanPaths` for persistent extra roots such as project-level `.codex` directories or imported Gemini/OpenClaw histories. Tokscale merges these paths with the default scan roots on every run and deduplicates overlapping roots by canonical path.
 
+Use `defaultClients` to pin a personal default — for example, set it to `["opencode", "claude"]` if those are the only clients you use, and `tokscale` (with no flags) will scope every report to them automatically. Pass `--client` on the command line to override for a single run.
+
 ### Environment Variables
 
 Environment variables override config file values. For CI/CD or one-off use:
@@ -807,7 +775,7 @@ tokscale graph --since 2024-01-01 --until 2024-12-31
 tokscale graph --year 2024
 
 # Filter by platform
-tokscale graph --opencode --claude
+tokscale graph --client opencode,claude
 
 # Show processing time benchmark
 tokscale graph --output data.json --benchmark