obsly-ai 0.3.0

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.

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.
• macOS menubar — Claude: xx% and Codex: yy% always visible, 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)
pip install obsly-ai

# With macOS menubar
pip install "obsly-ai[menubar]"

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

# Everything (for development)
pip install -e ".[all]"

Requires Python 3.10+.

Quickstart

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

# macOS menubar
obsly-ai menubar

# 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

Menubar

• Claude: xx% and Codex: yy% in the bar
• Claude weekly / Sonnet / 5h, Codex 7d / 5h, reset times, pace, recent session costs in the dropdown

obsly-ai menubar

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
  menubar.py            # macOS menubar [extra: menubar]
  proxy/                # LLM traffic proxy [extra: proxy]
  gitai/                # AI code attribution (zero deps)
saas/                   # Web product (landing, onboarding, dashboard)
tests/                  # pytest suite

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

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

MIT