claudinho

Claudinho ⚽

          

Live scores for the 2026 men's football tournament — in your terminal, your Claude Code / Cursor CLI statusline, and any MCP client. No API key, no signup; all 104 fixtures ship bundled, so the schedule works offline.

<p align="center"> <img src=".github/assets/hero.gif" alt="A Claude Code statusline flipping to a live World Cup score — South Korea 2–1 Czechia — while tests run in the terminal" width="800"> </p> <!-- HERO: real live-match capture from the Jun 11 opener — the statusline flips to South Korea's 81st-minute winner (1–1 → 2–1) while pytest runs. -->

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 — 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:

⚽ 🇳🇴 1–1 🇫🇷 87' · 🇸🇳 1–2 🇮🇶 86'

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

<!-- DEMO CARD: verbatim output of claudinho 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. --> ```text 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 or Anthropic. Try it: npx @claudinho/cli table A ```

⚠️ Not affiliated with, endorsed by, or connected to FIFA or Anthropic. 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

npm i -g @claudinho/cli
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:

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>

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 — ~/.cursor/cli-config.json: ``json { "statusLine": { "type": "command", "command": "claudinho prompt", "padding": 0, "updateIntervalMs": 1000, "timeoutMs": 1500 } } ``

MCP tools — ~/.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 # show only your team's match 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 ``

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

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:

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

Restart Claude Code to activate.

Monorepo / local dev? The init cursor / init claude aliases wire the global claudinho. To point a statusline or hook at a local build, use the granular commands with --command, e.g. claudinho init-cursor-statusline --command "node ./packages/cli/dist/index.js prompt" (and init-statusline / init-hook for Claude Code).

Other MCP clients — Codex, Claude Desktop, Windsurf, Zed, VS Code

codex mcp add claudinho -- npx -y @claudinho/mcp    # Codex CLI

Everything else takes the standard stdio config:

{ "mcpServers": { "claudinho": { "command": "npx", "args": ["-y", "@claudinho/mcp"] } } }

Then just ask, mid-task — the agent calls the MCP server and answers with the score:

<p align="center"> <img src=".github/assets/mcp-aha.gif" alt="An AI coding agent asked 'did Germany get through?' mid-task — it calls the Claudinho MCP server and answers with the result: Germany 1(3)–1(4) Paraguay, FT (Paraguay won on penalties)" width="720"> </p>

Surfaces

• CLI — today, live, next MEX, table, match <id>, bracket, markets, share, team (name → code, e.g. team "DR Congo") (plus vibe 😎 and star ⭐). --json on everything; TZ-aware via --tz.
• Live statusline — Claude Code & Cursor CLI — every live score inline; reads a local micro-cache, never blocks on the network. One command per agent: claudinho init claude / claudinho init cursor (also tmux & Starship via claudinho prompt).
• Score-aware hook (Claude Code) — a UserPromptSubmit hook that drops the live score into the model's context during matches; zero tokens off-match. (Cursor parity pending — its hook can't reliably inject context yet.)
• MCP server — 9 read-only tools (get_today, get_live, get_match, get_next_fixture, get_standings, get_bracket, get_market_signal, get_share_snippet, get_team) plus my_team / tournament_today prompts.
• Prediction-market signals — a read-only "who's favored" line (market-implied percentages, Source: Polymarket), shown only when a reliable market exists. Informational only — not betting advice. Opt out: --no-markets / CLAUDINHO_MARKETS=off.
• Shareable cards — claudinho share next MEX --copy puts a plain-text match card on your clipboard; claudinho share table A does the same for a group's live standings; claudinho share bracket for the knockout tree.

Speaks en / es / pt / fr, with optional localized commentary flair (¡GOOOOL!) — dial it down with --flavor subtle|off.

_Planned (not shipped yet):_ a desktop notifier and an AI pundit with a public accuracy scorecard.

FAQ

Do I need an API key or account? No. Nothing to sign up for; npx and done.

Does it work offline? The bundled data does — the full schedule, group fixtures, and the knockout bracket structure (all 104 fixtures ship bundled, no key). Anything live hits the network: scores, group standings, and a team's resolved knockout opponent (next once the draw fills in).

Where does the data come from? Live scores from ESPN's public scoreboard (attributed in output as Live data: ESPN); market signals from Polymarket public data. Rate limits respected.

Is the market line betting advice? No. It's read-only, informational-only market data with attribution — no trading, no links — and it never appears on the statusline or hook.

Why no crests, kits, or player photos? Legal-clean by design: facts and emoji flags only.

Flags show as boxed letters (CH, BA)? Some terminals — notably Warp — don't compose the regional-indicator pairs into flag glyphs, so 🇨🇭 renders as a boxed CH. claudinho auto-detects Warp and drops the flags: 3-letter codes on the statusline (MEX 1–0 RSA 67') and plain team names in the hook, today / live / table, and next. Force it anywhere with CLAUDINHO_FLAGS=off, or keep flags with CLAUDINHO_FLAGS=on.

Windows? Works, but flag emoji rendering varies by terminal — best on macOS/Linux. See the flags note above; CLAUDINHO_FLAGS=off gives clean codes on any terminal that can't render them.

Why star?

Claudinho is a solo, $0, organic fan project — a GitHub star is the only signal that it's worth maintaining, and the nudge to keep shipping through the final. A star also:

• surfaces it for other devs hunting live scores during the tournament,
• puts new releases in your feed — a desktop notifier, an AI pundit, and other tournaments are on the roadmap,
• takes one click → ⭐ star Claudinho.

New here? CONTRIBUTING.md has the layout, the dev loop, and good first issues.

Privacy Policy

Claudinho collects no personal data — no accounts, no telemetry, no analytics, no tracking. There is no Claudinho server. To show live results it makes read-only requests to public sports-data services (ESPN for scores/standings; Polymarket for informational-only market signals) with no account or personal data attached, and keeps a small cache in your local cache directory (~/.cache/claudinho). Full details: PRIVACY.md.

Security

Found a vulnerability? Please report it privately via GitHub's report form rather than a public issue. SECURITY.md has the disclosure process and the threat model (stdio only, no listener, no credentials, two read-only outbound hosts).

License

MIT © 2026 Arturo Garrido. All three packages publish with npm provenance via OIDC trusted publishing.

---

_Built while watching the games._ #VibingLaVidaLoca ⚽