Metadata-Version: 2.4
Name: obsly-ai
Version: 0.9.0
Summary: AI code intelligence: token tracking, attribution, cost analysis for Claude Code, Codex, Cursor
Author: Xavi Guardia
License: MIT
Project-URL: Homepage, https://ai.obsly.io
Project-URL: Documentation, https://ai.obsly.io
Keywords: claude,anthropic,dashboard,token,usage,ai-attribution,git-notes
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: menubar
Requires-Dist: rumps==0.4.0; extra == "menubar"
Requires-Dist: Pillow==11.1.0; extra == "menubar"
Provides-Extra: tray
Requires-Dist: pystray==0.19.5; extra == "tray"
Requires-Dist: Pillow==11.1.0; extra == "tray"
Requires-Dist: rumps==0.4.0; sys_platform == "darwin" and extra == "tray"
Provides-Extra: bitbar
Requires-Dist: matplotlib==3.10.1; extra == "bitbar"
Requires-Dist: numpy==2.2.4; extra == "bitbar"
Provides-Extra: proxy
Requires-Dist: mitmproxy==11.1.3; extra == "proxy"
Requires-Dist: flask==3.1.0; extra == "proxy"
Provides-Extra: dev
Requires-Dist: pytest==8.3.5; extra == "dev"
Requires-Dist: pytest-timeout==2.3.1; extra == "dev"
Provides-Extra: all
Requires-Dist: obsly-ai[bitbar,dev,menubar,proxy,tray]; extra == "all"

# 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

```bash
# 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:

```bash
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

```bash
# 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

```bash
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)

```bash
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

```bash
# 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

```bash
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)

```bash
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:

```text
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)
tests/                  # pytest suite
```

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

## Development

```bash
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.
