convez.ai
AgenteDevOps & InfraestruturaIntermediário
vatskyone

Claux — Monitor de Custo e Sessão para Claude Code

vatskyone/claux

Monitore custos e contexto do Claude Code em tempo real, sem surpresas na fatura

Ver no GitHub
InicialPluginScore · de 0 a 100

Ferramenta de monitoramento nativa para macOS que acompanha sessões do Claude Code em tempo real, mostrando custos vivos, saúde do contexto, projeções de burn-rate e histórico detalhado. Funciona localmente sem backend, lendo logs JSONL do Claude diretamente da máquina.

Instalação

$npx convez-ai vatskyone/claux

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
v1.18.0
Issues abertas
0
Contribuidores
2

Casos de uso

  • Monitorar gastos em tempo real de sessões do Claude Code
  • Rastrear saúde da janela de contexto e degradação do modelo
  • Atribuir custos a projetos específicos e modelos utilizados
  • Manter-se dentro de orçamentos mensais com alertas visuais
  • Analisar padrões de gasto com gráficos de 7 e 30 dias

Veredito

Claux resolve um problema real para usuários do Claude Code: falta de visibilidade nativa de custos e saúde do contexto. A implementação é sólida (Swift/SwiftUI no desktop, Rust na CLI), roda localmente sem dados externos, e oferece inteligência prática. Ferramenta essencial para quem trabalha com agentes autônomos e precisa controlar gastos.

README

A tradução para o português deste README ainda está na fila.


What is Claux?

Claude Code is Anthropic's agentic CLI — it writes code, runs commands, and iterates autonomously. It also bills per token. When you let an agent run for hours across multiple projects, the cost can quietly compound.

Claux watches every session so you don't have to.

No account. No backend. No data ever leaves your machine. Claux reads Claude Code's local JSONL session logs directly from ~/.claude/ and surfaces what matters: live session cost, context window health, plan-limit usage, and historical spend — all without interrupting your workflow.

ProblemImpact
No native cost visibilitySurprise bills at month-end
No context-window awarenessModel degradation before you notice
No session historyCan't attribute spend to projects
No spend pacingNo way to stay under a budget
No plan-limit visibilityUnexpected rate-limit interruptions

Claux ships as two independent tools:

DesktopCLI
RuntimeNative macOS menu bar app (Swift/SwiftUI)Terminal TUI + subcommands (Rust)
Primary usePassive monitoring, alerts, quick glanceDeep analysis, export, automation, scripting
Version1.16.30.7.8

Desktop app (macOS)

A native NSStatusItem + NSPopover menu bar app. Left-click toggles the popover; right-click opens a context menu. Runs invisibly at idle (~18 MB RSS). Requires macOS 13 Ventura or later.

Menu bar icon

StateAppearance
IdleStatic c monogram, system text color
Active sessionGreen c monogram with radial pulse animation
Optional overlaysLive cost in $ · Model badge

Right-click: Settings · Show in Menu Bar (Always / When session is active) · Quit.

Popover tabs

Dashboard

  • Live session card — cost, context health bar (green → yellow → red), token breakdown (input / output / cache read / cache write / thinking), burn rate ($/hr), cost projection, model badge, elapsed time
  • Session quality score — accepted edits, rejected actions, agent outcomes, touched files; accessible inline without switching tabs
  • CLAUDE.md quality score with color-coded grade
  • Plan limits card — 5-hour and 7-day Claude subscription usage bars with exact reset timestamps and countdowns

Analytics

  • 7-day spend chart and 30-day daily cost bar chart (SwiftUI Charts)
  • Per-project and per-model spend tables
  • Monthly budget progress bar (configurable, color-coded green/yellow/red)
  • Compact inline view in the popover; "Open full Analytics window" for the expanded view

History

  • Filterable session list with native search bar
  • Right-click rows: Copy Path, Show in Finder, Copy Session ID
  • Tap any row for full session detail: quality score, token breakdown, acceptance metrics, entrypoint badge

Notifications

All alerts use UNUserNotificationCenter and carry actions (Open Session / Open Dashboard / Snooze for today).

AlertTrigger
Cost thresholdSession spend crosses configurable limit (fires once per session)
Context windowFill % crosses configurable threshold (fires once per session)
Session endedRicher diagnostics on session close
Daily recapConfigurable hour — today's spend, session count, top project/model, in-app drill-down sheet
Weekly recapOptional Friday summary of the past 7 days

Verbosity modes — Minimal / Standard / Detailed, with quiet hours and weekday-only scheduling.

Settings

SettingOptions
Notification verbosityMinimal / Standard / Detailed
Quiet hoursConfigurable start/end
Daily & weekly recapScheduled hour, weekday-only toggle
Cost alert thresholdDollar amount
Context health alertPercentage
Show cost in menu barOn/Off
Show model badgeOn/Off
App themeLight / Dark / Auto
State color paletteSystem / Vivid / High Contrast / Colorblind Safe / Soft Contrast
Session retention7 / 14 / 30 / 60 / 90 days / Forever
Monthly budgetDollar amount ($0 = off)
Auto-refresh interval1 / 5 / 10 / 30 / 60 s
Launch at loginSMAppService
Session directoryCustom ~/.claude path
Include cache costOn/Off
Claude integrationInstall/repair the statusLine hook for plan-limit data

Build & run

git clone https://github.com/vatskyone/claux.git
cd claux/apps/desktop/Claux

# Build .app bundle and launch (required for notifications + login items)
bash build_app.sh run

# Build a drag-and-drop DMG installer → dist/Claux.dmg
bash build_dmg.sh

# Fast compile check (no bundle, notifications disabled)
swift build

build_app.sh run produces Claux.app, signs it ad-hoc, and opens it. The menu bar icon appears immediately.

Requirements: macOS 13 Ventura or later · Swift 5.9+ (Xcode 15+) · No third-party dependencies.


CLI app (Rust)

A terminal-first companion for deeper inspection, automation, and scripting. All subcommands are composable and support --json output. See apps/cli/README.md for the full reference.

TUI (claux tui)

A full-screen keyboard-driven dashboard with six tabs:

TabWhat it shows
DashboardToken breakdown bars + Usage panel (context fill, 5h limit, weekly budget, credit) + live Insights panel (cache grade, context health, cost projection, model, thinking %)
SessionsScrollable session list with tagging, cursor navigation, session detail overlay with source badge and CLAUDE.md breakdown
Analytics7-day bar chart · 30-day sparkline · monthly forecast · by-project and by-model tables with K tok/$ efficiency
AgentsLive sub-agent list with status, type, XP/level, quality stars, cost, duration; detail panel with token breakdown and output preview
SkillsSkill list from ~/.claude.json + ~/.claude/skills/ with star ratings and detail panel
HistoryNamed project checkpoints — save, restore, diff files since last checkpoint, write .claux/CONTEXT.md for agent consumption

Subcommands

claux status [--json]                                          Active session card
claux sessions [-n N] [--json]                                 Recent session table
claux spend [--json]                                           Today / week / month with trend arrows
claux analytics [--days N] [--json]                            Daily chart + monthly forecast + project + model breakdown
claux analytics local [--json] [--reset]                       On-device usage metrics

claux export [--format csv|json] [--output FILE] [-n N]        Export session history
claux tag <id> [label] [-r]                                    Attach or remove a label on any session
claux checkpoint save|list|load|delete                         Named project checkpoints

claux claudemd generate [--project PATH] [--write] [--json]    Generate a CLAUDE.md starter
claux claudemd improve  [--project PATH] [--write] [--backup]  Fill gaps in existing CLAUDE.md

claux account                                                  Account info + skill usage table
claux skills list|new|export|import                            Manage Claude Code skills
claux config get|set|unset|init <key>                          Budget limits and paths
claux doctor [--json]                                          Diagnose session discovery and parse health
claux completions zsh|bash|fish                                Shell completion scripts

Build & run

cd claux/apps/cli
cargo build --release
cargo run -- tui          # launch TUI
cargo run -- status       # quick status card

Requirements: Rust 1.78+ · macOS (primary target).


Architecture (desktop)

Sources/Claux/
├── ClauxApp.swift                # App entry point — NSStatusItem + NSPopover + NSMenu
│                                 # Left-click = popover, right-click = context menu
├── AppStore.swift                # @ObservableObject central state
│                                 # Owns SessionMonitor + RateLimitMonitor; computes all derived spend data
├── SessionMonitor.swift          # File-system engine
│                                 # DispatchSource watchers on ~/.claude/projects/**
│                                 # 10 s fallback poll timer · (URL, mtime) parse cache
├── SessionParser.swift           # JSONL → ClaudeSession
│                                 # Per-model pricing · per-turn daily cost attribution
│                                 # CLAUDE.md quality scorer (0–100) with TCC-safe traversal
│                                 # Session quality: accepted edits, rejected actions, agent outcomes
├── RateLimitMonitor.swift        # Watches ~/.claude/claux/rate_limits.json
│                                 # Publishes PlanLimitsSnapshot (5-hour + 7-day windows)
├── ClaudeStatusLineManager.swift # Installs/repairs the Claude statusLine integration
│                                 # Preserves any existing custom command
├── NotificationManager.swift     # UNUserNotificationCenter
│                                 # Cost · context · session-end · daily recap · weekly recap
│                                 # Verbosity modes, quiet hours, per-day delivery tracking
├── Models.swift                  # ClaudeSession · TokenUsage · SpendSummary
│                                 # DailySpend · ProjectSpend · ModelSpend · PlanLimitsSnapshot
├── Design.swift                  # AppVersion · semantic Color aliases · ModelInfo
│                                 # Format helpers · CardStyle · StateColorPreset
└── Views/
    ├── PopoverView.swift          # Root popover (Dashboard / Analytics / History tabs)
    │                              # Onboarding gating · session detail overlay
    ├── ActiveSessionCard.swift    # Live session stats card
    ├── PlanLimitsCard.swift       # 5h + 7d subscription usage bars + reset timestamps
    ├── DailyRecapSheet.swift      # In-app daily recap drill-down sheet
    ├── SpendSummaryView.swift     # Sparkline + spend cells + budget bar
    ├── RecentSessionsView.swift   # Session list with search filter
    ├── SessionRowView.swift       # Tappable row + right-click context menu
    ├── SessionDetailSheet.swift   # Full session breakdown + quality panel
    ├── ContextHealthBar.swift     # Animated fill bar
    ├── TokenBreakdownView.swift   # Token category breakdown
    ├── NoActiveSessionView.swift  # Empty state
    ├── OnboardingView.swift       # First-launch overlay (directory + integration + notifications)
    ├── SettingsView.swift         # General / Notifications / Data / About
    └── AnalyticsView.swift        # Analytics window (chart + project + model tables)

Data flow

~/.claude/projects/<encoded-path>/*.jsonl
        │
        ▼  DispatchSource (kernel-level file events) + 10 s poll
SessionMonitor
        │  mtime cache — only re-parses changed files
        ▼
SessionParser.parse(url:activeSessionIds:)
        │  → ClaudeSession { dailyCosts: [Date: Double], qualityScore, tokenUsage, … }
        ▼
AppStore.updateUI(from:)          ◄── RateLimitMonitor (rate_limits.json watcher)
        │  computeSpend · computeDailySpend · computeProjectBreakdown · computeModelBreakdown
        ▼
SwiftUI views — published on RunLoop.main

Key engineering decisions

Per-turn cost attribution — Cost and timestamp are recorded for every assistant turn, building a [Date: Double] map keyed by local-timezone day-start. Sessions that run past midnight split correctly across today / yesterday / this week / this month.

Incremental parse cache — SessionMonitor maintains a [URL: (mtime: Date, session: ClaudeSession)] dictionary. Only files whose contentModificationDate has changed are re-parsed. A ten-session workspace with one active session re-parses exactly one file per tick.

Active session detection — Two signals with OR: (1) ~/.claude/sessions/<pid>.json contains a sessionId matching the JSONL filename; (2) file mtime < 90 seconds.

TCC-safe CLAUDE.md traversal — The CLAUDE.md scorer explicitly skips macOS privacy-protected home directories (Desktop, Documents, Downloads, Movies, Music, Pictures) to prevent unexpected permission prompts during session parsing.

AppKit menu bar — MenuBarExtra intercepts all mouse events at the NSStatusItem level, making SwiftUI's .contextMenu inoperative. Claux uses a native NSStatusItem + NSPopover + NSMenu stack so left-click deterministically toggles the popover and right-click reliably shows a context menu on all macOS versions.

Theme propagation — NSPanel windows ignore SwiftUI's .preferredColorScheme(). AppThemeModifier sets NSApp.appearance directly on .onAppear and .onChange, propagating the chosen theme to every window in the process.


Why native Swift, not Electron

Claux (Swift/SwiftUI)Electron alternative
Memory at idle~18 MB~200 MB+
Launch time<0.3 s2–4 s
Menu bar renderingNative NSStatusItemCustom WebView chrome
macOS notificationsUNUserNotificationCenterNode.js shim
Launch at loginSMAppServiceWorkaround scripts
File watchingDispatchSource kernel eventschokidar (polling)
App size<2 MB150 MB+

Pricing reference

ModelInputOutputCache readCache write
claude-opus-4.x$15.00 / M$75.00 / M$1.50 / M$18.75 / M
claude-sonnet-4.x$3.00 / M$15.00 / M$0.30 / M$3.75 / M
claude-haiku-4.x$0.80 / M$4.00 / M$0.08 / M$1.00 / M

Model ID matching uses substring (opus / sonnet / haiku) so new model versions are picked up automatically.


Roadmap

Near-term

  • Global keyboard shortcut to toggle the popover (⌃⌥C, user-configurable)
  • Anomaly detection — flag sessions with unusual cost spikes
  • CLAUDE.md improvement suggestions surfaced inline in the desktop app
  • iCloud sync for lifetime spend totals across multiple Macs

Longer-term

  • CSV / JSON export from the desktop app
  • Slack / webhook alert integration
  • Team spend aggregation (local network, no external server)

Contributing

# 1. Fork and clone
git clone https://github.com/vatskyone/claux.git

# Desktop — edit apps/desktop/Claux/Sources/Claux/
# Bump AppVersion.current in Sources/Claux/Design.swift
# Add a CHANGELOG.md entry, then:
cd apps/desktop/Claux && bash build_app.sh run

# CLI — edit apps/cli/src/
# Bump version in Cargo.toml, add a CHANGELOG.md entry, then:
cd apps/cli && cargo test && cargo build

Read apps/desktop/Claux/CLAUDE.md before submitting desktop changes. Every PR must include a version bump and a changelog entry.


Project structure

claux/
├── apps/
│   ├── desktop/
│   │   └── Claux/                  # Swift package (macOS app)
│   │       ├── Sources/Claux/      # All Swift source files
│   │       ├── Package.swift
│   │       ├── build_app.sh        # Build + launch script
│   │       ├── build_dmg.sh        # Build drag-and-drop DMG installer
│   │       ├── CLAUDE.md           # AI coding guidelines
│   │       └── CHANGELOG.md        # Full desktop version history
│   └── cli/
│       ├── src/                    # Rust source files
│       │   ├── commands/           # Subcommand handlers (tui, status, export, …)
│       │   ├── models.rs           # ClaudeSession, AgentRun, Checkpoint, …
│       │   ├── parser.rs           # JSONL parsing + CLAUDE.md scoring
│       │   ├── monitor.rs          # Session discovery + mtime cache
│       │   ├── spend.rs            # Spend aggregation + forecasting
│       │   └── tui.rs              # Terminal UI rendering
│       ├── Cargo.toml
│       ├── README.md               # Full CLI reference
│       └── CHANGELOG.md            # Full CLI version history
├── docs/                           # Product and engineering docs
├── packages/                       # Shared packages (future)
└── README.md

Ver o original no GitHub

Bom para

Relacionados