claudinho

# Claudinho ⚽

[![CI](https://github.com/arturogarrido/claudinho/actions/workflows/ci.yml/badge.svg)](https://github.com/arturogarrido/claudinho/actions/workflows/ci.yml)
[![npm: @claudinho/cli](https://img.shields.io/npm/v/@claudinho/cli?label=%40claudinho%2Fcli&color=cb3837)](https://www.npmjs.com/package/@claudinho/cli)
[![npm: @claudinho/mcp](https://img.shields.io/npm/v/@claudinho/mcp?label=%40claudinho%2Fmcp&color=cb3837)](https://www.npmjs.com/package/@claudinho/mcp)
[![npm downloads](https://img.shields.io/npm/dm/@claudinho/cli?label=downloads&color=cb3837)](https://www.npmjs.com/package/@claudinho/cli)
[![cursor.directory](https://img.shields.io/badge/cursor.directory-claudinho-0b0b0b)](https://cursor.directory/plugins/claudinho)
[![Smithery: listed](https://img.shields.io/badge/Smithery-listed-5b3df5)](https://smithery.ai/servers/arturogarrido/claudinho)
[![Glama: A](https://img.shields.io/badge/Glama-A-2ea043)](https://glama.ai/mcp/servers/arturogarrido/claudinho)
[![node](https://img.shields.io/node/v/@claudinho/cli?color=5fa04e)](https://nodejs.org)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![#VibingLaVidaLoca](https://img.shields.io/badge/%23VibingLaVidaLoca-⚽-ff5a5f)](https://github.com/arturogarrido/claudinho)
[![GitHub stars](https://img.shields.io/github/stars/arturogarrido/claudinho?style=flat&logo=github&label=stars&color=f5c518)](https://github.com/arturogarrido/claudinho)

**Live football scores, fixtures and standings for the competition you follow (the World Cup, the Premier League, LALIGA, the Champions League and 12 more) in your terminal, your Claude Code and Cursor CLI statusline, and MCP clients.** No API key, no signup. The World Cup's 104 fixtures ship bundled; the other competitions' schedules are read from the feed. It ran the 2026 World Cup from the opener to the final.

<p align="center">
  <img src=".github/assets/hero.png" alt="The claudinho live list in a terminal during a UEFA Nations League matchday: nine matches in play at 48' to 50', each row with its flags, score, minute and a commentary phrase or a rally cry (England 2–0 Czechia, Croatia 1–0 Spain, Scotland 1–0 Slovenia)" width="800">
</p>
<!-- HERO: a real capture, `claudinho --competition nations-league live` on Oct 6, 2026, the
     second half of the UEFA Nations League's 11:45 PDT batch (nine matches in play) and
     the first matchday 0.11 ran. Not a recording: the command's real output at that moment,
     rendered to a PNG. -->

```bash
npx @claudinho/cli follow nations-league   # choose a competition once (follow --list shows them all)
npx @claudinho/cli today      # try it in 10 seconds — no install, no key
npx @claudinho/cli live       # what's on right now (during match windows)
```

> ⭐ **Like it?** [Star the repo](https://github.com/arturogarrido/claudinho): a fan project's only scoreboard is its stars. (`claudinho star` shows you how anytime.)

While matches are live, your Claude Code or Cursor CLI statusline reads (the same moment as the capture above, eight matches shown and one counted):

```text
⚽ 🇦🇱 1–0 🇸🇲 49' · 🇧🇾 1–0 🇫🇮 50' · 🇭🇷 1–0 🇪🇸 50' · 🏴󠁧󠁢󠁥󠁮󠁧󠁿 2–0 🇨🇿 50' · 🇪🇪 0–0 🇮🇸 50' · 🇱🇺 0–2 🇧🇬 50' · 🇲🇩 0–2 🇸🇰 49' · 🏴󠁧󠁢󠁳󠁣󠁴󠁿 1–0 🇸🇮 48' +1
```

And `claudinho share` prints a card made for the group chat:

<!-- DEMO CARD: verbatim output of `claudinho --competition world-cup --tz UTC share table A`.
     Chosen over a single match card because it has no fixed date to go stale (a
     played-and-passed fixture reads as abandoned). Standings still drift across
     matchdays: REGENERATE periodically, especially before any conversion-sensitive
     moment. Never hand-edit. Re-rendered on 2026-10-05 (0.11) through the CLI's own
     `share table A` command, offline: a provider double served the capture's Group A
     rows, at a frozen clock of 2026-06-28T12:00Z. -->
```text
World Cup · standings

Group A · standings

1. 🇲🇽 MEX  9 pts · 3-0-0 · +6
2. 🇿🇦 RSA  4 pts · 1-1-1 · -1
3. 🇰🇷 KOR  3 pts · 1-0-2 · -1
4. 🇨🇿 CZE  1 pts · 0-1-2 · -4

Live data: ESPN
#VibingLaVidaLoca · Independent fan project · Not affiliated with FIFA, any confederation, league or club, or Anthropic.
Try it: npx @claudinho/cli --competition world-cup table A
```

> ⚠️ **Not affiliated with FIFA, any confederation, league or club, or Anthropic. Nor endorsed by or connected to any of them.**
> Claudinho is an independent, open-source fan project. It displays factual match data
> (scores, fixtures, standings) and uses emoji flags only: no logos, emblems, kits,
> broadcast footage, or player likenesses.

## Install

### Just the CLI

```bash
npm i -g @claudinho/cli
claudinho follow world-cup     # choose once: every command, the statusline and the hook follow it
claudinho today
claudinho next MEX --tz America/Mexico_City --lang es
```

### Cursor CLI: statusline + MCP

One command wires the live-score statusline and prints the MCP config to paste:

```bash
npm i -g @claudinho/cli
claudinho init cursor          # statusline → ~/.cursor/cli-config.json (+ the MCP paste)
```

<p align="center">
  <img src=".github/assets/cursor-cli-statusline.png" alt="A live World Cup score in a Cursor CLI statusline (Uzbekistan 0–1 Colombia, 42') with a model and context line below it" width="520">
</p>
<p align="center"><sub>Captured during the 2026 World Cup group stage.</sub></p>

Restart your agent session to see it. Prefer to paste it yourself? `claudinho init cursor --print`
emits the snippets, or copy them straight from here:

**Statusline**, in `~/.cursor/cli-config.json`:
```json
{
  "statusLine": {
    "type": "command",
    "command": "claudinho prompt",
    "padding": 0,
    "updateIntervalMs": 1000,
    "timeoutMs": 1500
  }
}
```

**MCP tools**, in `~/.cursor/mcp.json` (global) or a project `.cursor/mcp.json`:
```json
{ "mcpServers": { "claudinho": { "command": "npx", "args": ["-y", "@claudinho/mcp"] } } }
```

**Optional env**: a model + context line below the score, or scope to your team:
```bash
export CLAUDINHO_CURSOR_META=auto   # model + context % line under the score (recommended)
export CLAUDINHO_TEAM=MEX           # your team's match first (the others counted); or pin one: claudinho follow <alias> --team <name>
export CLAUDINHO_FLAGS=off          # 3-letter codes instead of flag emoji (already automatic in Warp)
export CLAUDINHO_DEBUG=1            # print data-provider failure diagnostics to stderr
export CLAUDINHO_NO_STAR=1          # suppress the occasional "star the repo" nudge
```

> **Note:** Cursor's `beforeSubmitPrompt` hook doesn't yet reliably inject context into the
> model, so the score-aware *hook* stays Claude Code-only for now; the statusline and MCP
> server work great in Cursor.

### Claude Code: statusline, score-aware hook, MCP

```bash
npm i -g @claudinho/cli
claudinho init claude          # statusline + live-score hook, then the MCP one-liner
```

`init claude` backs up `~/.claude/settings.json` first and is idempotent. Prefer the pieces
à la carte? Run `init-statusline`, `init-hook`, and:

```bash
claude mcp add claudinho -- npx -y @claudinho/mcp
```

Restart Claude Code to activate.

#### Claude Code plugin

The plugin draws the live score or the countdown above the prompt (the band), raises a toast when a
score changes, and puts the live-score block beside each prompt for the model while a match is on,
all from the installed CLI (`claudinho ambient --json`), never a fetch of its own. Install the CLI
(0.11.2 or later: an older one's band shows nothing and nothing toasts) and follow a competition, then run `claudinho init plugin` first: it removes the statusline
(`claudinho prompt`) and the live-score hook (`claudinho hook`) that `init claude` wrote to
`~/.claude/settings.json`, keeps every other setting, and prints the install line and the MCP
one-liner. It removes those two exact commands only: an edited one (a wrapper,
`npx -y @claudinho/cli hook`) stays where it is, and the command names it for you. Then, at the
prompt of a Claude Code session in a terminal:

```
/plugin install claudinho --marketplace arturogarrido/claudinho
```

Answer `y` to add the marketplace, then choose a scope. The `toasts` option (in `/config`) is
`pinned` by default (your pinned team's match, `claudinho follow <alias> --team <name>`; with no pin
saved, no toast), `all` or `off`. A toast is the hook's own line for the match (with its flags and
the roster's names on a nations competition), one per match per change, and best effort, never every
goal: a change is never said as it happens from a view the CLI could not vouch for (stale, degraded,
or a read that was not whole), a goal across such a gap or a failed run is said at the first current
view after it (late, never lost while the match stays in the list: one gone from the next current
view and back is observed afresh), and the first view of a match says nothing. At the end of an
edition the band shows the World Cup's sign-off line, the one end-of-edition line the statusline
prints; after another competition's season the statusline says nothing is known, and the band shows
nothing. More in the plugin's
[README](https://github.com/arturogarrido/claudinho/tree/main/packages/plugin#readme).

#### For a program: `claudinho ambient --json`

The statusline and the hook as one JSON object on one line, for a program that draws them itself:
`line` (what `claudinho prompt` prints; `--columns N`, N a positive integer, fits it to N columns,
the `+N` count kept), `context` (the hook's block, or `null`), `live` (the live matches, each marked
`picked` and `pinned`), `current` (whether that list is a current snapshot's, the read that filled
it was whole: an empty list means nothing is on only when it is), `next` (the fixture the countdown names), `pick`, `competition`,
`degraded`, `source`, `updatedAt`, `staleAfter` (when its live scores stop being shown) and
`disclaimer` (the non-affiliation sentence). Beside `line` th