Metadata-Version: 2.4
Name: obsly-ai
Version: 0.9.7
Summary: Iria Monitor — AI code intelligence: token tracking, attribution, cost analysis for Claude Code, Codex, Cursor
Author: Xavi Guardia
License: MIT
Project-URL: Homepage, https://monitor.iria.tech
Project-URL: Documentation, https://monitor.iria.tech
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"
Requires-Dist: playwright==1.50.0; extra == "dev"
Requires-Dist: pytest-playwright==0.5.2; extra == "dev"
Provides-Extra: all
Requires-Dist: iria-monitor[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.

## 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.

```bash
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/`](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)

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

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

## 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)

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

### Run

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