Skip to content

docs(readme): document minutelyTabEnabled and the optional Minutely tab #568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
junhoyeo merged 1 commit into from
May 18, 2026
Merged

docs(readme): document minutelyTabEnabled and the optional Minutely tab #568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions README.ja.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,6 +496,21 @@ Tokscaleは設定を`~/.config/tokscale/settings.json`に保存します：
| `nativeTimeoutMs` | number | `300000` | ネイティブサブプロセス処理の最大時間（5000-3600000ms） |
| `defaultClients` | string[] | `[]` | `--client/-c` フラグを渡さない場合に適用されるクライアントフィルター。`--client` と同じ ID を受け付けます（例: `["opencode", "claude", "synthetic"]`）。未知の ID は無視されます。CLI フラグが指定されるとこのリストは完全に無視されます — マージはしません。 |
| `light.writeCache` | boolean | `false` | `true` のとき、`tokscale --light` はレンダリング直後に TUI キャッシュを原子的に上書きします。CLI フラグ `--write-cache` / `--no-write-cache` が実行ごとに優先されます。 |
| `minutelyTabEnabled` | boolean | `false` | TUI に分単位の Minutely タブを表示し、データ読み込み時に分単位の集計を実行します。分単位の粒度はほとんどのユーザーにとってニッチな診断ビューであり、大規模データセットでは分単位のバケット処理に無視できないコストがかかるため、既定では無効になっています。 |

#### Minutely タブの有効化

Minutely タブはトークン使用量を分単位で表示し、バーストパターンの診断、単一セッションのデバッグ、`autoRefreshEnabled` と組み合わせたほぼリアルタイムの監視に最も有用です。分単位の集計はデータ読み込み時にすべての解析済みメッセージを処理するため、ほとんどのユーザーには不要な RAM と CPU コストが発生します。そのため既定では非表示になっています。

有効化するには、`~/.config/tokscale/settings.json` で `minutelyTabEnabled` を `true` に設定します：

```json
{
"minutelyTabEnabled": true
}
```

再起動後、タブストリップの Hourly と Stats の間に Minutely タブが表示され、Tab / BackTab / Left / Right ナビゲーションがそれを循環します。フラグを `false` に戻すとタブは再び非表示になり、集計もスキップされます。

#### キャッシュディレクトリ構成

Expand Down
15 changes: 15 additions & 0 deletions README.ko.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -495,6 +495,21 @@ Tokscale은 설정을 `~/.config/tokscale/settings.json`에 저장합니다:
| `nativeTimeoutMs` | number | `300000` | 네이티브 서브프로세스 처리 최대 시간 (5000-3600000ms) |
| `defaultClients` | string[] | `[]` | `--client/-c` 플래그를 전달하지 않을 때 적용되는 기본 클라이언트 필터. `--client`와 동일한 ID를 받습니다 (예: `["opencode", "claude", "synthetic"]`). 알 수 없는 ID는 자동으로 무시됩니다. CLI 플래그가 있으면 이 목록은 완전히 무시됩니다 — 병합되지 않습니다. |
| `light.writeCache` | boolean | `false` | `true`이면 `tokscale --light`가 렌더링 직후 TUI 캐시를 원자적으로 덮어씁니다. CLI 플래그 `--write-cache` / `--no-write-cache`가 실행별로 우선합니다. |
| `minutelyTabEnabled` | boolean | `false` | TUI에 분 단위 Minutely 탭을 표시하고 데이터 로딩 중에 분 단위 집계를 수행합니다. 대부분의 사용자에게 분 단위 세분화는 틈새/진단 뷰이며, 대규모 데이터셋에서는 분 단위 버케팅에 무시할 수 없는 비용이 들기 때문에 기본적으로 비활성화되어 있습니다. |

#### Minutely 탭 활성화

Minutely 탭은 토큰 사용량을 분 단위로 표시하며, 버스트 패턴 진단, 단일 세션 디버깅, `autoRefreshEnabled`와 함께 거의 실시간 모니터링에 가장 유용합니다. 분 단위 집계는 데이터 로딩 중 모든 파싱된 메시지를 처리하므로 대부분의 사용자에게는 불필요한 RAM과 CPU 비용이 발생합니다. 그래서 기본적으로 숨겨져 있습니다.

활성화하려면 `~/.config/tokscale/settings.json`에서 `minutelyTabEnabled`를 `true`로 설정하세요:

```json
{
"minutelyTabEnabled": true
}
```

재시작 후 탭 스트립의 Hourly와 Stats 사이에 Minutely 탭이 나타나며, Tab / BackTab / Left / Right 내비게이션이 이를 순환합니다. 플래그를 다시 `false`로 설정하면 탭이 숨겨지고 집계도 다시 건너뜁니다.

#### 캐시 디렉터리 레이아웃

Expand Down
19 changes: 17 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ In the age of AI-assisted development, **tokens are the new energy**. They power
## Features

- **Interactive TUI Mode** - Beautiful terminal UI powered by Ratatui (default mode)
- 6 interactive views: Overview, Models, Daily, Hourly, Stats, Agents
- 6 interactive views: Overview, Models, Daily, Hourly, Stats, Agents (plus an optional Minutely view, opt-in via `minutelyTabEnabled`)
- Keyboard & mouse navigation
- GitHub-style contribution graph with 9 color themes
- Real-time filtering and sorting
Expand Down Expand Up @@ -246,7 +246,7 @@ tokscale models --json > report.json # Save to file

The interactive TUI mode provides:

- **6 Views**: Overview (chart + top models), Models, Daily, Hourly, Stats (contribution graph), Agents
- **6 Views**: Overview (chart + top models), Models, Daily, Hourly, Stats (contribution graph), Agents. A seventh per-minute view (Minutely) is hidden by default and can be enabled with `minutelyTabEnabled` in `settings.json` — see [Configuration](#configuration)
- **Keyboard Navigation**:
- `1-6` or `←/→/Tab`: Switch views
- `↑/↓`: Navigate lists
Expand Down Expand Up @@ -522,12 +522,27 @@ Tokscale stores settings in `~/.config/tokscale/settings.json`:
| `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. |
| `light.writeCache` | boolean | `false` | When true, `tokscale --light` overwrites the TUI cache atomically after rendering. CLI flags `--write-cache` / `--no-write-cache` override per-invocation. |
| `minutelyTabEnabled` | boolean | `false` | Show the per-minute Minutely tab in the TUI and aggregate per-minute usage during data loading. Default-off because minute-granularity is a niche/diagnostic view for most users and the per-minute bucketing has a non-trivial cost on large datasets. |
| `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.

#### Enabling the Minutely tab

The Minutely tab shows a per-minute breakdown of token usage and is most useful for diagnosing burst patterns, debugging a single session, or watching activity in near-real-time alongside `autoRefreshEnabled`. It is hidden by default because the per-minute aggregation runs over every parsed message during data loading, which adds RAM and CPU cost that most users do not need.

To enable it, set `minutelyTabEnabled` to `true` in `~/.config/tokscale/settings.json`:

```json
{
"minutelyTabEnabled": true
}
```

After restart, the Minutely tab appears between Hourly and Stats in the tab strip, and Tab / BackTab / Left / Right navigation cycles through it. Set the flag back to `false` to hide the tab and skip the aggregation again.

#### Cache directory layout

The regenerable CLI/TUI/pricing/Wrapped caches now live under `~/.config/tokscale/cache/` (or `${TOKSCALE_CONFIG_DIR}/cache/` when overridden). Antigravity sync artifacts remain at `~/.config/tokscale/antigravity-cache/`:
Expand Down
15 changes: 15 additions & 0 deletions README.zh-cn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,6 +496,21 @@ Tokscale 将设置存储在 `~/.config/tokscale/settings.json`：
| `nativeTimeoutMs` | number | `300000` | 原生子进程处理最大时间（5000-3600000ms） |
| `defaultClients` | string[] | `[]` | 未传递 `--client/-c` 选项时应用的客户端筛选。接受与 `--client` 相同的 ID（例如 `["opencode", "claude", "synthetic"]`）。未知 ID 会被静默丢弃。命令行选项会完全覆盖此列表 — 不会合并。 |
| `light.writeCache` | boolean | `false` | 为 `true` 时，`tokscale --light` 会在渲染完成后以原子方式覆盖 TUI 缓存。CLI 标志 `--write-cache` / `--no-write-cache` 会按次运行覆盖该设置。 |
| `minutelyTabEnabled` | boolean | `false` | 在 TUI 中显示按分钟的 Minutely 标签，并在数据加载期间执行分钟级聚合。对大多数用户而言，分钟级粒度是较为小众的诊断视图，而在大数据集上分钟分桶有非平凡的代价，因此默认关闭。 |

#### 启用 Minutely 标签

Minutely 标签按分钟显示 Token 使用情况，最适合用于诊断突发模式、调试单个会话，或与 `autoRefreshEnabled` 配合进行近实时监控。分钟级聚合在数据加载期间会遍历所有已解析的消息，对大多数用户来说带来不必要的 RAM 与 CPU 开销。因此默认情况下它是隐藏的。

要启用它，请在 `~/.config/tokscale/settings.json` 中将 `minutelyTabEnabled` 设为 `true`：

@cubic-dev-ai cubic-dev-ai Bot May 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: This instruction hardcodes ~/.config/tokscale/settings.json and omits the TOKSCALE_CONFIG_DIR override, so users with a custom config root may edit the wrong file.

(Based on your team's feedback about resolving config paths via the configured root override.)

View Feedback

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At README.zh-cn.md, line 505:

<comment>This instruction hardcodes `~/.config/tokscale/settings.json` and omits the `TOKSCALE_CONFIG_DIR` override, so users with a custom config root may edit the wrong file.

(Based on your team's feedback about resolving config paths via the configured root override.) </comment>

<file context>
@@ -496,6 +496,21 @@ Tokscale 将设置存储在 `~/.config/tokscale/settings.json`：
+
+Minutely 标签按分钟显示 Token 使用情况，最适合用于诊断突发模式、调试单个会话，或与 `autoRefreshEnabled` 配合进行近实时监控。分钟级聚合在数据加载期间会遍历所有已解析的消息，对大多数用户来说带来不必要的 RAM 与 CPU 开销。因此默认情况下它是隐藏的。
+
+要启用它，请在 `~/.config/tokscale/settings.json` 中将 `minutelyTabEnabled` 设为 `true`：
+
+```json
</file context>
Suggested change
要启用它，请在 `~/.config/tokscale/settings.json` 中将 `minutelyTabEnabled` 设为 `true`：
要启用它，请在配置文件 `settings.json` 中将 `minutelyTabEnabled` 设为 `true`（默认路径为 `~/.config/tokscale/settings.json`；若设置了 `TOKSCALE_CONFIG_DIR`，则使用 `${TOKSCALE_CONFIG_DIR}/settings.json`）：


```json
{
"minutelyTabEnabled": true
}
```

重启后，Minutely 标签将出现在标签栏中 Hourly 与 Stats 之间，Tab / BackTab / Left / Right 导航将会在其间循环。把该标志再设为 `false` 可隐藏标签并再次跳过聚合。

#### 缓存目录布局

Expand Down