obsly-ai 0.9.7

Iria Monitor — AI code intelligence: token tracking, attribution, cost analysis for Claude Code, Codex, Cursor

obsly-ai

AI code intelligence: token tracking, attribution, and cost analysis for Claude Code, Codex, and Cursor.

obsly-ai is one place to see what your AI coding agents are spending, what's left in your usage windows, and which lines of code they actually wrote. It works locally, supports Claude Max + Codex side by side, and ships a zero-dependency core so you can drop it into any agent's process without a virtualenv dance.

Product site: https://ai.obsly.io

What you get

• Live dashboard — Claude weekly / Sonnet / 5h utilization and Codex 7d / 5h windows in one view, with burndown charts and live API calls.
• Tray icon (macOS / Windows / Linux) — Claude: xx% and Codex: yy% always visible in the menubar (macOS) or system tray (Windows / Linux), with reset times and pace in the dropdown.
• AI code attribution (gitai) — git-notes-based record of which code each AI agent wrote, queryable with ai-blame and ai-stats. Zero dependencies, runs in agent hooks.
• LLM proxy (optional) — mitmproxy addon that captures provider, model, tokens, cost, repo, branch, and git user from intercepted API calls. Enterprise team dashboard included.

Claude stays on its own calculation path. Codex is added as a separate source with its own cycle and resets — never forced into Claude's billing window.

Installation

# Core: dashboard + gitai attribution (zero dependencies)
pipx install obsly-ai

# With cross-platform tray icon (macOS menubar + Windows/Linux system tray)
pipx install "obsly-ai[tray]"

# Legacy: macOS-only menubar (rumps backend)
pipx install "obsly-ai[menubar]"

# With LLM proxy + team dashboard
pipx install "obsly-ai[proxy]"

# Everything (for development, from a clone)
pip install -e ".[all]"

Requires Python 3.10+. If you don't have pipx yet:

brew install pipx && pipx ensurepath   # macOS
python3 -m pip install --user pipx && python3 -m pipx ensurepath   # Linux

pipx is the recommended installer for Python CLIs: it puts obsly-ai on your PATH in an isolated venv that survives brew upgrade python.

Quickstart

# Live web dashboard at http://localhost:8765
obsly-ai live

# Tray icon (macOS menubar / Windows / Linux system tray)
obsly-ai tray

# One-shot analytics
obsly-ai analyze
obsly-ai burndown
obsly-ai report

The legacy claude-dashboard entrypoint is kept as an alias.

Main views

Live dashboard

• Claude weekly utilization, Sonnet utilization, and 5h window
• Codex 7d used / left, 5h used, reset times, plan type
• Claude burndown chart + separate Codex chart from local session logs
• Live API calls, session costs, and recent activity

obsly-ai live
obsly-ai live --no-browser --port 8765

Tray icon (macOS / Windows / Linux)

• Claude: xx% and Codex: yy% in the macOS menubar or the Windows/Linux system tray
• Claude weekly / Sonnet / 5h, Codex 7d / 5h, reset times, pace, recent session costs in the dropdown
• On macOS the native rumps backend is used; on Windows/Linux the icon runs via pystray (GNOME users need the "AppIndicator and KStatusNotifierItem Support" extension for the tray icon to show up)

obsly-ai tray          # cross-platform
obsly-ai menubar       # legacy alias, same entrypoint

AI code attribution (gitai)

obsly-ai ships a zero-dependency attribution engine that records which AI agent wrote each line of code, stored in refs/notes/ai (git notes). It installs hooks into Claude Code, Codex, Cursor, and Windsurf so attribution happens automatically as the agent edits files.

Install the hooks

# Install hooks into every detected agent (Claude Code, Codex, Cursor, Windsurf)
# plus pre-commit / post-commit / post-rewrite hooks in the current repo
obsly-ai ai-install

# Or target a single agent
obsly-ai ai-install --agent claude-code
obsly-ai ai-install --dry-run        # preview without writing

# Check what's wired up
obsly-ai ai-status

# Remove hooks
obsly-ai ai-uninstall

ai-install writes to each agent's own settings file (~/.claude/settings.json, ~/.codex/hooks.json, ~/.cursor/hooks.json, ~/.codeium/windsurf/hooks.json) and to .git/hooks/ in the current repo. It never touches your git config, staging area, or working tree.

Query attribution

ai-blame path/to/file.py            # like git blame, with AI agent + session per line
ai-blame path/to/file.py -L 40,80   # limit to a line range
ai-blame path/to/file.py --cost     # join with proxy cost data

ai-stats                            # recent commits, % AI per commit
ai-stats --repo                     # repo-wide breakdown by agent / author
ai-stats --durability               # how much AI-written code survives over time

The whole gitai/ package uses only Python stdlib so it can run safely inside any agent's process without polluting their environment.

AI Usage Coach

A privacy-first, local-only reflection tool for developers using AI assistants (Claude Code, GitHub Copilot, Codex). The coach reads your local session logs, computes DORA-flavored personal metrics (throughput, lead time, personal failure rate, wellbeing), and produces a weekly coaching note.

Filosofía: DORA 2026 — AI is an amplifier. The greatest returns come from improving the underlying system. This coach is the bottom-up: each developer reflects on their own usage, privately. No central control, no rankings, no surveillance.

obsly-ai coach --output-dir ~/.obsly-ai/coach
obsly-ai coach --no-llm                       # heuristics only, no claude CLI required
obsly-ai live                                  # then open http://127.0.0.1:8765/coach

The coach/ package is Tier 1 (zero external dependencies). Subprocess to claude -p is hidden behind an injectable LLMRunner; the dashboard works with heuristics only when the CLI isn't installed.

Next task (in progress on feat/coach-blocks)

The coach is being refactored from flat prose to typed visual blocks (text / dora / chart / table / quote / callout). The new design measures delivery from git, evidence files and merged PRs — never from how noisy your AI sessions were — and the LLM is given those facts as bindings it cannot contradict. Personal DORA with directional verdicts (better, steady, watch, worse) against the user's own 4-week median replaces Google-tier labels.

The whole metrics + decision pipeline is designed to be extensible by companies: the default delivery_signals.py (git + filesystem + gh + Claude session logs) and personal_dora.py (DF/LT/CFR/MTTR) ship as one possible implementation. Through a public extension API (SignalSource, MetricComputer, BlockRenderer protocols plus user-editable ~/.obsly-ai/coach/prompt.md), adopters can plug Jira, Tempo, GitHub Issues, git-notes, Linear, PagerDuty, or anything else with a few lines of glue and zero core patches.

• Plan and acceptance criteria: tasks/coach-blocks/
• Tracking issue: see GitHub issues
• Current state: foundation in place (blocks.py + delivery_signals.py shipped with full TDD on feat/coach-blocks); remaining 6 tasks (personal DORA, prompt rewrite, render port, emoji cleanup, live wiring, extension API) up next.

LLM proxy + team dashboard (optional)

pip install "obsly-ai[proxy]"
obsly-ai proxy        # start mitmproxy with the obsly addon
obsly-ai server       # team dashboard at http://localhost:8800
obsly-ai doctor       # health checks for proxy + cert + storage

Captures every LLM API call (Anthropic, OpenAI, Mistral, DeepSeek) and attributes it via PID → cwd → git remote → branch → git config user.email. Events are persisted as JSONL locally and aggregated in the team dashboard.

Data sources

Claude

Reads the Claude Code OAuth token from macOS Keychain (Claude Code-credentials) and calls:

GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <your token>
anthropic-beta: oauth-2025-04-20

That's the same utilization source behind /usage. It also parses ~/.claude/projects/**/*.jsonl for per-call detail.

Codex

Local-only, from ~/.codex/sessions/**/*.jsonl. Parses token_count events and uses:

• rate_limits.secondary.used_percent → 7-day window
• rate_limits.primary.used_percent → 5-hour window
• resets_at → reset times
• plan_type when present

Privacy

• All log parsing is local
• Claude project logs and Codex session logs are read-only
• The only outbound call is the Claude usage API to Anthropic, using your own local OAuth token
• The proxy stores events locally as JSONL by default; the team dashboard is opt-in

Project layout

claudedashboard/        # Core package
  cli.py                # Unified entrypoint (obsly-ai / claude-dashboard)
  live.py               # Live SSE dashboard (port 8765)
  analyze.py            # Text analytics
  burndown.py           # Weekly burndown
  report.py             # One-shot HTML report
  tray.py               # Cross-platform tray icon [extra: tray]
  menubar.py            # macOS menubar rumps backend [extra: menubar]
  proxy/                # LLM traffic proxy [extra: proxy]
  gitai/                # AI code attribution (zero deps)
saas/                   # Web product (landing, onboarding, dashboard)
  app/domain/           # DDD domain layer (value objects, services, events)
  app/db/models.py      # SQLAlchemy OLTP models
docs/                   # Architecture docs (data lake spec, questionnaire)
tests/                  # pytest suite

See CLAUDE.md for development guidelines (TDD, dependency tiers, hook safety rules).

Data Lake (analytics layer)

The SaaS includes a Medallion data lake architecture for business intelligence:

• Bronze: raw domain events (append-only, JSONB)
• Silver: cleaned, enriched, deduplicated events with tenant validation
• Copper: parking lot for events that fail enrichment (auto-retry)
• Gold: star schema with 8 fact tables + 11 dimensions, RLS, SCD Type 2

Pipeline runs every 15 minutes via Cloud Scheduler. Promotion gates between layers ensure data quality. See docs/datalake-gold-schema.md for the full spec.

Development

pip install -e ".[all]"
pytest tests/ -v

The project follows strict TDD and a three-tier dependency policy: core + gitai/ are pure stdlib, optional features are pinned in pyproject.toml extras, dev tools are isolated. See CLAUDE.md for details.

Visual smoke tests (Playwright)

The Live dashboard and Coach tab are verified with Playwright + Chromium. These tests catch regressions invisible to unit tests — e.g. an empty Chart.js canvas after a CSS reflow, or a Coach block rendered but without data.

Setup (one-time)

make playwright-install
# or manually: pip install -e ".[dev]" --break-system-packages && python3 -m playwright install chromium

Run

# Fast smoke (no LLM calls, ~30s)
make playwright-smoke

# Full flow with real claude -p haiku (~$0.10, opt-in)
make playwright-slow

Evidence

Screenshots are captured to tasks/live-playwright-smoke/evidence/ on every run:

• home.png — Live dashboard full page
• coach-full.png — Coach tab full page
• coach-{hero,top3,dora,trends,wellbeing,weekly,sessions}.png — per-block

The directory is git-ignored (only .gitkeep is versioned). Keep screenshots locally to diff across runs when a visual regression is suspected.

Regression-guard test

test_home_chart_has_visible_data polls window.weekChart.data.datasets[0].data and fails if the chart datasets never populate within 10s — designed to catch the exact incident where the chart silently went empty after editing the <h1>.

License

The published obsly-ai wheel on PyPI is distributed under the MIT license. The source repository (SoftForYou/obsly-ai) is private; this README lives inside that private repo and is not a claim of open-source development. See the PyPI project page for the canonical license of the released artifact.