# streakr

> A drop-in, framework-agnostic Git contribution calendar for the web. It normalizes
> activity from GitHub, GitLab and Bitbucket into one daily series, and splits out the
> commits co-authored by AI agents (Claude, Codex, opencode, Copilot) as their own sources.

streakr is an MIT-licensed vanilla JavaScript library published on npm as
`@rosado-io/streakr`. It ships ESM plus a single stylesheet and has zero runtime
dependencies. It is not a React component and requires no build step.

## What it renders

One component with two layouts, chosen by **container width, not user agent**:

- **Heatmap** — a 53-week GitHub-style grid, drawn when the container is 520px or wider.
- **Ring** — a radial year view, drawn below 520px.

It also computes four figures from the normalized series: Total Contributions, Best
Streak, Current Streak (swapped for Active Rate on past years), and Active Days.

## Data sources

| Source | Kind | Notes |
| --- | --- | --- |
| GitHub | REST / GraphQL | Public users need no token; a token adds private counts. |
| GitLab | REST | gitlab.com or self-hosted via a custom base URL. |
| Bitbucket | REST | Workspace commits folded into the same daily series. |
| Claude, Codex, opencode, Copilot | `Co-authored-by:` trailers | Matched from commit messages, each counted as its own source. |

Local clones can be scanned with `localGitCoAuthorProvider` across every branch and
remote with no token — nothing leaves the machine. Providers can also be skipped
entirely by passing your own array of dates and counts to `getDays`.

## Install

```bash
npm install @rosado-io/streakr
```

```js
import { createStreakr } from '@rosado-io/streakr'
import '@rosado-io/streakr/styles.css'

createStreakr({
  target: document.querySelector('#streakr'),
  theme: 'dark',
  years: [2024, 2025, 2026],
  getDays: (year) => fetchActivity(year),
})
```

## Links

- Live demo: https://streakr-js.web.app/
- Source: https://github.com/rosado-io/streakr
- Package: https://www.npmjs.com/package/@rosado-io/streakr
- Docs: https://github.com/rosado-io/streakr#readme
- Providers: https://github.com/rosado-io/streakr/blob/main/docs/providers.md
- License: MIT