obsly-ai 0.9.4

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.

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.

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.