저는 현재 Arch Linux와 KDE Plasma 6 환경에서 Claude Code, Codex, Gemini (agy를 통한 커맨드 라인 사용), 그리고 DeepSeek를 사용하고 있습니다. 저뿐만 아니라 많은 이들에게 있어 문제는 어떤 모델에 할당량(quota)이 남아 있는지 아는 것이 되었습니다. 특히 이미 많은 컨텍스트(context), 검토된 파일들, 그리고 한 시간 동안의 반복 작업이 포함된 작업을 수행 중일 때는 더욱 그렇습니다.

그래서 저는 KDE 패널을 위한 뷰어, 즉 HUD를 만들게 되었습니다. 각 에이전트에게 남은 여유 공간이 얼마인지, 그리고 할당량이 언제 초기화되는지를 보여주는 네 개의 인디케이터(indicator)입니다. 별도의 탭도, 별도의 대시보드도 필요 없습니다. 그리고 무엇보다 중요한 것은, 작업을 마무리하거나 git rebase를 하는 도중에 할당량이 다 떨어져서 당황하는 일이 없다는 점입니다 😱.

첫 번째 스푼: 토큰 주(token-week)

각 제공업체는 우리가 얼마나 사용할 수 있는지를 측정하는 자신만의 방식을 만들어냈습니다.

Claude는 시간과 일 단위의 윈도우(window)로 말합니다. Codex는 플랜에서 사용 가능한 윈도우를 보고합니다. Gemini는 요청(request)에 대한 로컬 추정치를 필요로 합니다. 반면, DeepSeek는 금전적 잔액(monetary balance)으로 이야기합니다.

네 명의 에이전트, 네 개의 시계, 그리고 공유되지 않는 단위.

업계는 다소 특이한 것을 달성했습니다. 바로 **토큰 시간(token-hours)**과 **토큰 주(token-weeks)**를 실제 계획 단위로 변환한 것입니다. 이제는 작업이 얼마나 걸릴지 묻는 것만으로는 충분하지 않습니다. 에이전트가 저를 예전 방식으로 일하게 내버려 두기 전에 작업을 마칠 수 있을지도 계산해야 합니다 :).

패널에서 저는 이를 네 개의 링, 즉 도넛 형태로 축소했습니다. 거의 가득 찬 링은 에이전트에게 여유가 있음을 의미합니다. 거의 비어 있는 링은 아마도 에이전트에게 그동안의 서비스에 감사 인사를 전하고 다음 에이전트를 시도해 볼 시간임을 의미합니다.

그림 1 — KDE Plasma 패널의 컴팩트한 AI 할당량 HUD 뷰. 네 개의 링은 에이전트별 가용 마진(margin)을 요약하여 보여줍니다. 출처: 데모 데이터를 사용한 직접 스크린샷.

그 위에 마우스를 올리면 각 윈도우의 세부 정보와 초기화 시간이 표시됩니다:

그림 2 — 툴팁 (Tooltip)은 활성 작업 (Active task)을 떠나지 않고도 윈도우 (Windows)와 초기화 시간 (Reset times)을 보여줍니다. 출처: 데모 데이터를 사용한 직접 스크린샷.

위젯을 열면 네 명의 에이전트 (Agents) 모두에 대한 전체 세부 정보가 표시됩니다:

그림 3 — KDE 패널에서 상세 보기로 이어지는 AI 할당량 HUD (AI Quota HUD) 데모. 패널, 툴팁, 팝업은 하나의 로컬 소스를 읽습니다. 표시된 값은 데모 데이터이며 개인의 할당량을 나타내지 않습니다. 출처: 직접 화면 녹화.

두 번째 스푼: 순서가 아닌 데이터가 결정한다

첫 번째 버전은 몇 주 동안 잘 작동했습니다. Codex는 두 개의 윈도우를 반환했습니다: 짧은 5시간짜리 윈도우와 주간 윈도우였습니다.

제 코드는 이를 위치에 따라 해석했습니다:

1. 첫 번째 윈도우, 즉 바깥쪽 링 (Outer ring)은 5시간짜리였습니다.
2. 두 번째는 주간 윈도우였습니다.

단순했습니다—Codex가 스키마 (Schema)를 변경하기 전까지는 말이죠.

어느 날 위젯은 소위 "5h" 윈도우에서 5%가 사용 가능하다고 표시했지만, 초기화는 6일 후에 예정되어 있었습니다. 기술 기업이라 할지라도, 5시간이 거의 일주일 동안 지속된다는 것은 지나친 혁신처럼 보였습니다.

원시 응답 (Raw response)에는 단 하나의 윈도우가 포함되어 있었습니다:

604800 seconds

이는 7일입니다.

Codex는 짧은 윈도우를 보고하는 것을 중단했지만, 제 코드는 여전히 가장 먼저 나타나는 것을 "5h"라고 불렀습니다. 동시에, "마지막 유효한 값 유지" 로직이 실패한 쿼리 (Query)와 더 이상 존재하지 않는 윈도우를 구분할 수 없었기 때문에, 기존의 주간 윈도우는 캐시 (Cache)에 동결된 상태로 남아 있었습니다. 👻

수정 작업은 두 부분으로 이루어졌습니다.

첫째, 각 윈도우는 더 이상 위치로 식별되지 않고 실제 지속 시간 (Duration)으로 식별되기 시작했습니다. 짧은 지속 시간은 세션 (Session)이며, 연장된 지속 시간은 주간 윈도우 또는 그에 상응하는 것입니다.

둘째, 모니터는 이제 다음을 구분합니다:

• 실패한 쿼리 (a query that failed): 이 경우 이전 값을 일시적으로 유지하고 이를 캐시됨 (cached)으로 표시합니다.
• 더 이상 윈도우를 포함하지 않는 유효한 쿼리 (a valid query that no longer contains a window): 이 경우 현재 상태에서 해당 윈도우를 제거합니다.

인터페이스 또한 모든 에이전트 (agent)가 동일한 구조를 가진다고 가정하는 것을 중단했습니다. 두 개의 윈도우가 도착하면 더블 도넛 (double donut)을 그립니다. 하나가 도착하면 단일 링 (single ring)을 그립니다. 데이터가 인터페이스를 정의하며, 그 반대는 아닙니다.

이 교훈은 작지만 상당히 일반적입니다: 만약 제공자 (provider)가 지속 시간 (duration)을 제공한다면, 그것이 데이터의 정체성 (identity)입니다. 배열 내에서의 위치는 단지 일시적인 우연일 뿐입니다.

세 번째 스푼: 로컬(local)하며 유용하지만, 그리 보편적이지는 않은

이 프로젝트는 크로스 플랫폼 (cross-platform) 애플리케이션을 지향하지 않습니다.

저는 제 환경과 매우 유사한 환경을 위해 이것을 만들었습니다:

• Arch Linux
• KDE Plasma 6
• systemd --user
• Python
• Bash
• QML
• 제가 이미 사용 중인 도구들의 로컬 세션 (local sessions) 및 자격 증명 (credentials)

아마도 Plasma 6를 실행하는 다른 배포판 (distributions)에도 적응할 수 있을 것입니다. 하지만 GNOME, Plasma 5, Windows 또는 macOS에서 변경 없이 작동할 것이라고 약속하지는 않습니다. 또한 가능한 모든 인증 (authentication) 방법을 추상화하지도 않았습니다. 이것은 제가 정리하여 게시하기로 결정한 제 자신의 데스크톱을 위한 도구이지, 가능한 모든 운영 체제, 제공자, 그리고 요금제의 조합을 해결하려는 시도가 아닙니다.

내부적으로 경로는 짧습니다:

                 systemd --user timer
                          │
                     every five minutes
...

_헬퍼 (helpers)_는 자격 증명 (credentials)을 건드리는 유일한 컴포넌트입니다. 이들은 인증 토큰 (authentication tokens)이나 대화 내용 없이 정제된 JSON을 반환합니다.

Python 모니터는 정보를 쿼리 (query), 검증 (validate), 그리고 병합 (merge)합니다. 만약 timeout, 만료된 자격 증명, 또는 429 에러를 만나면, 마지막으로 알려진 값을 유지하고 이를 캐시됨 (cached)으로 표시합니다.

systemd 타이머는 5분마다 업데이트를 실행합니다. 이 위젯은 제공자(provider)에게 직접 쿼리를 보내지 않으며, 0600 권한을 가진 로컬 파일만 읽습니다. 이를 통해 _속도 제한 (rate limit)_을 너무 자주 확인하여 오히려 _속도 제한 (rate limit)_을 유발하는 상황을 방지할 수 있으며, 이는 루프를 닫는(closing the loop) 특히 우아한 방법이 될 것입니다. 🫠

동일한 status.json 파일은 MCP 서버에 의해 읽힐 수 있습니다. 이를 통해 에이전트(agent)는 작업을 위임하기 전에 어떤 제공자에게 여전히 할당량(quota)이 남아 있는지 물어볼 수 있습니다. 데스크톱 바와 오케스트레이터(orchestrator)는 정확히 동일한 상태를 전달받습니다.

결론 (Closing)

이 저장소는 MIT 라이선스 하에 공개되어 있습니다. KDE Plasma 6를 위해 설계되었으며, sudo 권한이 필요하지 않고 사용자의 로컬 경로에 설치됩니다:

git clone https://github.com/tatanlabra/ai-quota-kde.git
cd ai-quota-kde
scripts/install-user.sh
...

GitHub에서 저장소 보기

이 도구는 더 많은 할당량을 만들어내거나, 더 나은 요금제를 협상하거나, 토큰 부족 현상을 제거하지는 못합니다. 단지 작업을 수행하는 도중에 선택한 에이전트가 추가 할당량을 찾아 떠나버렸다는 사실을 깨닫는 상황을 방지해 줄 뿐입니다 🤑.

이것은 내 워크플로우에 대한 주권(sovereignty)을 아주 조금이나마 확보하는 방법입니다. 즉, 얼마나 남았는지, 언제 초기화되는지, 그리고 다음 작업 전달(handoff)을 누가 받아야 하는지를 아는 것입니다.

그림 4 — 컴파일 중 (Compiling), xkcd no. 303, Randall Munroe 작. 과거에는 코드가 컴파일 중이라는 것이 변명이었지만, 이제는 할당량이 다음 주에 초기화된다고 말할 수 있습니다. CC BY-NC 2.5 라이선스 하에 배포됩니다.