【ITニュース解説】I built a desktop widget that turns my Claude Code, Codex and Cursor limits into a pixel hero's HP

ニュース記事は、AIアシスタントツールの利用状況を分かりやすく管理するためのデスクトップウィジェット「Token Slayer」の開発について語っている。このウィジェットは、普段から複数のAIツール、具体的にはClaude Code、Codex、Cursorなどを使いこなす開発者が、それぞれの利用制限（リミット）をいちいち確認する手間を省くために作られたものだ。各ツールの利用制限は、それぞれ異なる場所で確認する必要があり、次にどのAIエージェントを使うべきかを判断するために何度もチェックするのが面倒だったという、開発者ならではの課題が背景にある。

Token Slayerは、常にデスクトップ画面の最前面に表示される小さなウィジェットとして機能する。このアプリの核心的なコンセプトは、各AIサービスの残り利用量をピクセルアートのヒーローのHP（ヒットポイント）として視覚的に表現することだ。例えば、Claude Code、Codexの5時間および週ごとの利用制限、Cursorの月間利用制限が、それぞれヒーローのHPバーとして表示される。AIエージェントが実際に動作している間は、ヒーローは「戦闘」している状態になり、何も作業をしていないアイドル状態のときは、ヒーローは焚き火のそばで「休息」するというユニークな演出が加わっている。これにより、ユーザーはゲーム感覚でAIツールの利用状況を把握できる。

このウィジェットの主な機能は多岐にわたる。まず、先述の通り、各AIサービスの残り利用量をHPとしてリアルタイムで表示する。また、AIエージェントが作業を開始すると、そのローカルでの活動を監視し、数秒以内にはヒーローの動きに反映されるため、ユーザーは視覚的にエージェントの稼働状況を把握できる。さらに、「Runway prediction（滑走路予測）」という機能も搭載されており、過去30分間の利用状況から、現在のペースで使い続けた場合にいつ利用制限に達するかを予測し、もしリセット時間よりも早く制限に達しそうであれば「OUT 1H20」（残り1時間20分で利用制限に達する）といった警告を表示する。これは、リミットオーバーを防ぎ、計画的に利用するために非常に役立つ。

また、Token Slayerにはユニークなレベルアップシステムも導入されている。ユーザーはAIツールの利用制限を使うことで経験値（XP）を獲得し、ヒーローをレベルアップさせることができる。これは、利用制限を使い切ることを奨励するための仕組みで、特に週ごとや月ごとのリセットが近づいていて、まだ多くの利用量が残っている場合、「BURNING TIME」として獲得XPが倍増する。これは、使わなかった利用量はリセット時に失われるため、もったいないという心理を逆手にとって、計画的な利用を促す工夫だ。その他にも、64種類もの実績（アチーブメント）や、非常に珍しい伝説のドラゴンが登場する要素、そして毎週の利用状況を記録したカードを生成する機能など、ゲーム性を高めるための様々な要素が盛り込まれている。ヒーローのクラス（海賊、シェフ、バイキングなど）や、登場する敵、休憩シーンなど、17種類の無料の見た目のカスタマイズも可能であり、さらにオプションで有料のコスメティックパックも提供されているが、アプリ本体は無料で利用できる。このアプリはmacOSとWindowsの両方に対応しており、ユーザーのプライバシーにも配慮されている。アナリティクス機能はなく、開発者自身のサーバーとも通信しない。利用状況のデータは各AIサービスのAPIから直接取得し、有料パックのライセンス認証時のみライセンスサービスと通信する仕組みだ。

開発過程においては、いくつかの予期せぬ困難に直面したという。最も難しかった課題の一つは、「AIエージェントが現在作業中であるか」を正確に判断することだった。当初、macOSではファイルの変更を監視するfs.watch機能を使ってみたが、AIアプリが既存のファイルに追記する際に、その追記イベントが正しく発生しないことが多く、期待通りに動作しなかった。CursorというAIツールでは、SQLiteデータベースの更新ログ（WALファイル）の変更を数えることも試したが、AIアプリがアイドル状態でも約30秒ごとにこのファイルが更新されるため、作業中かどうかの判別が困難でノイズが多かった。最終的に、Cursorのエージェントが生成するトランスクリプトファイルの最終行を読み取り、それが「ターン終了」を示すレコードでなく、かつ最近ファイルが更新されていれば、現在作業中であると判断するという方法が採用された。この解決策は、Musterというオープンソースアプリからヒントを得たものだ。

二つ目の課題は、ローカル環境で取得できる利用状況の数値と、サーバー側で管理されている実際の数値との間にズレが生じることだった。例えば、Codexのローカルセッションファイルから計算した残り利用量が78%であるのに対し、アカウントページでは72%と表示されることがあった。これは、他のデバイスやウェブ経由でのAI利用が、ローカルのファイルには反映されないためだった。この問題に対処するため、アプリはサーバー側から取得した公式の数値を優先し、ローカルの数値はサーバーにアクセスできない場合の予備としてのみ利用する方針に切り替えられた。

三つ目の課題は、ClaudeやCursorといったAIサービスの「利用状況API」が、一般に公開されているAPIではなく、それぞれのアプリが内部的に利用する非公開のエンドポイントであったことだ。これらのAPIは開発者向けにドキュメント化されておらず、予告なしに変更される可能性があるため、アプリの安定性に影響を与えるリスクがあった。このため、Token SlayerではAPIからのエラーが発生した場合、それを「不明なエラー」として扱い、すぐに動作を停止させるのではなく、最後に取得できた正しい値を表示し続けることで、ユーザー体験を損なわないようにしている。また、CursorのAPIから一時的に不正な認証エラー（401エラー）が返された事例もあったが、これはElectronというフレームワークが共有するCookieが原因で、古いCookieがリクエストに付加されてしまっていたことが判明した。Cookieなしでリクエストを送信することでこの問題は解決された。

最後の課題は、サーバーから一時的に誤った利用状況の数値が報告されることで発生した。ある時、サービスが短時間だけ「0%使用済み」と報告し、その後すぐに正しい値に戻ったことがあったが、Token Slayerはこの一時的な「0%」を新たな利用と誤認識し、ヒーローのレベルが夜間に急激に12まで上がってしまった。このような誤ったレベルアップを防ぐため、同じリセット期間内で急激な利用量の増減があった場合は、即座に反映せずに、もう一度確認用のデータが来るまで待機するという修正が加えられた。これにより、データの信頼性が向上した。

Token Slayerは、AIツールを日常的に利用する開発者のための実用的かつエンターテインメント性豊かなツールとして提供されている。macOSとWindows向けに無料でダウンロード可能で、Windows版についてはまだコード署名がされていないため、初回起動時にWindows SmartScreenから警告が表示されることがあるが、ダウンロードファイルごとに提供されるSHA256SUMS.txtを用いてファイルの完全性を確認できる。開発者は、特にWindowsユーザーや、自身がテストしていない利用プランのユーザーからのフィードバックを積極的に求めており、今後も対応するAIエージェントの拡充なども視野に入れているようだ。このアプリは、AI技術をより身近で楽しいものにするための、クリエイティブなアプローチの一例と言えるだろう。