Your loyal watchdog for Claude Code tokens.
Tu guardián fiel para los tokens de Claude Code.
If you use Claude Code daily, you know the feeling: you're deep into a critical refactor, hours of accumulated context, and suddenly — limit reached. No warning. No time to save your progress. Your entire flow, gone.
Si usas Claude Code a diario, conoces la sensación: estás en medio de un refactor crítico, llevas horas de contexto acumulado, y de repente — límite alcanzado. Sin aviso. Sin tiempo para guardar tu progreso. Todo tu flujo, perdido.
DogClaud is a desktop app that lives in your system tray like a loyal watchdog. It connects directly to your claude.ai account, monitors your real token usage in real time, and barks at you before it's too late.
DogClaud es una app de escritorio que vive en tu bandeja del sistema como un guardián fiel. Se conecta directamente a tu cuenta de claude.ai, monitorea tu consumo real de tokens en tiempo real, y te ladra antes de que sea demasiado tarde.
It doesn't estimate. It knows exactly how much you've used and how much you have left.
No estima. Sabe exactamente cuánto has usado y cuánto te queda.
- Direct sync with the claude.ai API every 30 seconds
- Login with your account — data shown only with an active web session
- Without a session, the app shows a neutral state (no fake data)
- Current session (5-hour window) with countdown to reset
- Weekly consumption (7-day window) with countdown to reset
- Traffic light colors: green → blue → yellow → orange → red
- 6 thresholds: 25%, 50%, 75%, 90%, 95%, 100%
- 3 beeps with unique frequency per level (1 kHz to 4 kHz)
- Native OS notifications
- Zero alerts on startup — only triggers when usage rises and crosses a new threshold
- Individually silenceable per threshold
- Changes color based on your current consumption level
- Tooltip with percentage and time remaining until reset
- Context menu with full usage summary
- Define usage blocks per day
- Organize your week to maximize your tokens strategically
| Plan | Session (5 h) | Weekly (7 d) |
|---|---|---|
| Pro | ~7,000 tokens | ~100,000 tokens |
| Max 5 | ~35,000 tokens | ~500,000 tokens |
| Max 20 | ~140,000 tokens | ~2,000,000 tokens |
Download from Releases:
Linux:
# AppImage (any distro)
chmod +x DogClaud-1.1.0.AppImage
./DogClaud-1.1.0.AppImage
# Debian / Ubuntu
sudo dpkg -i dogclaud_1.1.0_amd64.debmacOS:
Download the .zip, extract and drag to Applications.
Windows:
Run the .exe installer from Releases.
git clone https://github.com/thl-corporation/dogclaud.git
cd dogclaud
npm install
npm run electron:dev- Open the app — it minimizes to the system tray
- Click the dog icon to open the window
- In the Usage tab, press Connect
- Login with your claude.ai account
- Done — real data in seconds
git clone https://github.com/thl-corporation/dogclaud.git
cd dogclaud
npm install
npm run electron:dev # Full app (build + Electron)
npm run dev # Dev server with hot reload (port 61983)
npx tsc --noEmit # Quick type check
npm run dist:linux # AppImage + .deb
npm run dist:mac # .zip for macOS
npm run dist:win # .exe installer (must be built on native Windows — see note below)
npm run update # Full update: close app → pull → build → install .deb → restartWindows build note: The
dist:wincommand requires a native Windows environment. Building on Linux/macOS via Wine is not supported becauseelectron-builderusesrceditto modify the.exemetadata, which depends on Windows-native DLLs. To build the Windows installer:
- Clone the repo on a Windows machine
- Install Node.js (v18+)
- Run
npm install && npm run dist:win- The
.exeinstaller will be generated in therelease/folder
src/
├── main/index.ts # Electron main process
├── preload/index.ts # Secure IPC bridge (contextBridge)
├── renderer/
│ ├── App.tsx # Main layout + alert logic
│ ├── components/
│ │ ├── gauges/ # SessionGauge, WeeklyGauge (circular SVG)
│ │ ├── alerts/ # AlertManager (threshold buttons)
│ │ ├── settings/ # SettingsPanel
│ │ ├── scheduler/ # WeeklyPlan
│ │ ├── WebUsagePanel # claude.ai API data
│ │ └── SetupScreen # Initial setup wizard
│ ├── stores/ # Zustand (usage, alerts, settings)
│ └── hooks/ # useClaudeUsage
├── core/
│ ├── parser/ # Incremental JSONL log reader
│ ├── calculator/ # Usage calculation per time window
│ ├── audio/ # Tone generator (Web Audio API)
│ └── constants.ts # Limits, thresholds, sound config
└── shared/types.ts # Shared TypeScript types
Contributions are welcome! / ¡Las contribuciones son bienvenidas!
- Fork this repository
- Create a branch from
develop:git checkout -b feature/my-improvement develop - Make your changes and verify:
npx tsc --noEmit - Open a Pull Request against
develop
The
mainbranch is protected. All changes go throughdevelopvia PR.
See CONTRIBUTING.md for full guidelines.
| Layer | Technology |
|---|---|
| Desktop | Electron 28 |
| Frontend | React 18 + TypeScript 5 + Tailwind CSS 3 |
| State | Zustand 4 |
| Audio | Web Audio API (oscillator + gain) |
| Monitoring | Chokidar 3 (file watching) |
| Persistence | electron-store 8 |
| Build | Vite 5 + vite-plugin-electron |
| Packaging | electron-builder (AppImage, deb, zip, exe) |
- Fix: False 100% usage on startup — alerts no longer fire on app launch
- Fix: Alert system not triggering when crossing new thresholds after initial sync
- Fix: Taskbar icon not showing in Linux task managers (WM_CLASS mismatch)
- New: Circular app icons for a polished look
- New:
npm run update— one-command update script (close, pull, build, install, restart) - Perf: Optimized incremental JSONL parsing and reduced unnecessary re-renders
- Initial release with real-time token monitoring, claude.ai API sync, smart alerts, system tray integration, and weekly planner
- No hardcoded API keys, tokens or credentials
- Web session cookies stored locally (electron-store), never transmitted to third parties
- Main process logs don't expose UUIDs, emails, org names or cookie values
- Dev server on non-standard port (61983) to avoid conflicts
| Creator | THL Corporation |
| CEO | Eliezer López |
| Web | thlcorporation.com |
| Contact | contacto@thlcorporation.com |
| GitHub | github.com/thl-corporation |
| License | MIT |
DogClaud is developed and maintained by THL Corporation from Chile.
MIT License — use, modify and distribute freely.
Made with love by THL Corporation from Chile