claudinho

Your Claude Code celebrates when your team scores.

Claudinho puts live football beside your coding agent. The Claude Code plugin (a Claude Code mod) shows the score above your prompt, says your team’s goals in a toast, celebrates them with the Claude mascot and opens a match pane with the goals and cards. The MCP server lets any agent answer “how is my team doing?” mid-task, and the CLI and statusline bring the same scores to your terminal. It follows the competition you choose: the World Cup, the Premier League, LALIGA, the Champions League and 12 more (Liga MX, Serie A, the Bundesliga, the Libertadores and the rest are in the table below). No API key, no signup, no account.

Set it up in one step

In Claude Code, paste this prompt. Claude asks which competition and team you follow, installs the CLI, follows your choice, checks that it works, and hands you the one line you type yourself:

Set up Claudinho, the live football plugin for Claude Code. If you cannot run commands on
my computer, say so and stop. Run only the commands named here, and nothing else. Before
you run anything, ask me which competition to follow (for example the Premier League,
LALIGA, Liga MX, the Champions League or the World Cup) and which team to pin, if any, and
wait for my answers. Then run `node --version`: if it is older than 22, stop and tell me
to install Node.js 22 or later. Install the CLI with `npm i -g @claudinho/cli`, then run
`claudinho follow --list` to find the alias of my competition. Run
`claudinho follow <alias>`, or `claudinho follow <alias> --team <my team>` if I named one;
if it cannot pin the team, show me what it printed and ask me again. Run
`claudinho init plugin`: it removes Claudinho's own statusline and prompt hook from Claude
Code's settings if an earlier setup wrote them, and changes nothing otherwise. Check the
setup with `claudinho next` if I pinned a team, else `claudinho today`, and show me what
it printed. You cannot install a plugin yourself, so as the last step tell me to type
`/plugin install claudinho --marketplace arturogarrido/claudinho` at the prompt of Claude
Code in a terminal (the desktop app cannot run it), answer `y` to add the marketplace, and
press Enter for the user scope. Then tell me how to undo all of it:
`claude plugin uninstall claudinho@claudinho`, `claudinho follow off`, then
`npm rm -g @claudinho/cli`, and tell me that the saved choice and the cache folders are
listed under "Where it is saved" in the CLI's README:
https://github.com/arturogarrido/claudinho/tree/main/packages/cli#where-it-is-saved

On default permission settings Claude asks you to approve each command. The plugin’s install line is a slash command, which only you can type, so that step stays yours. The same steps by hand: Claude Code plugin.

Try it

npx @claudinho/cli follow champions-league   # choose your competition once
npx @claudinho/cli today                     # today's matches, in your timezone
npx @claudinho/cli live                      # the matches in play right now

Claudinho needs Node.js 22 or later. That is the oldest line it runs on, not a security level: run a patched release of the Node 22 or 24 line.

Your league instead? follow premier-league, follow liga-mx, follow laliga: every alias is in Competitions. Add --lang es (or pt, fr) for Spanish, and pin your team with follow champions-league --team Arsenal.

Pick your setup

Start with the first row and add what you want. Every row but the MCP server needs the claudinho command from the first row. The plugin replaces the Claude Code statusline and the prompt hook: use the plugin or those two rows, not both.

You want	What it changes	Command
Scores in the terminal	installs the claudinho command; it keeps your choice and a cache on your machine (where)	npm i -g @claudinho/cli
The live score under your Claude Code prompt	Claude Code’s statusline	claudinho init-statusline
The live score above your Claude Code prompt, a toast and a celebration on a goal, and a match pane	installs a Claude Code plugin	Claude Code plugin
Claude Code to know the live score when you ask it something	adds a prompt hook (the plugin does this too)	claudinho init-hook
The live score in Cursor’s terminal agent (Cursor CLI)	Cursor CLI’s statusline	claudinho init cursor
To ask your agent about football	adds an MCP server (a set of tools your agent can call)	MCP server

The statusline and the plugin’s band read a local cache and never wait on the network. The plugin’s match pane is different: it runs claudinho match <id>, which asks the data provider. Off-match, the prompt hook adds nothing to what the model reads.

Competitions

Nothing is followed until you choose one. claudinho follow <alias> saves your choice (a name or a short form works too: claudinho follow epl), and the commands, the statusline, the plugin and the MCP server follow it. Three things stay the World Cup’s whatever you follow: claudinho team and the MCP tool get_team read its nations, and the MCP resource fixtures://{date} is its bundled schedule. claudinho team is refused when --competition or CLAUDINHO_COMPETITION chooses another competition. claudinho follow --list lists every alias with what it offers, claudinho follow shows your choice, and claudinho follow off forgets it.

Alias	Competition	Teams	Scores	Next	Standings	Bracket	Markets
world-cup	World Cup	nations	yes	yes	yes	yes	yes
euro	EURO	nations	yes	yes	yes	not yet	not yet
copa-america	Copa América	nations	yes	yes	yes	not yet	not yet
nations-league	UEFA Nations League	nations	yes	yes	yes	not yet	not yet
concacaf-nations-league	Concacaf Nations League	nations	yes	yes	yes	not yet	not yet
gold-cup	Gold Cup	nations	yes	yes	yes	not yet	not yet
premier-league	Premier League	clubs	yes	yes	yes	n/a	not yet
laliga	LALIGA	clubs	yes	yes	yes	n/a	not yet
serie-a	Serie A	clubs	yes	yes	yes	not yet	not yet
bundesliga	Bundesliga	clubs	yes	yes	yes	not yet	not yet
liga-mx	Liga MX	clubs	yes	yes	yes	not yet	not yet
liga-auf	Liga AUF Uruguaya	clubs	yes	yes	yes	not yet	not yet
champions-league	Champions League	clubs	yes	yes	yes	not yet	not yet
libertadores	Libertadores	clubs	yes	yes	yes	not yet	not yet
concacaf-champions-cup	Concacaf Champions Cup	clubs	yes	yes	n/a	not yet	not yet
club-world-cup	Club World Cup	clubs	yes	yes	yes	not yet	not yet

yes offered · not yet not offered yet · n/a the competition has no such thing (a league season with no knockout tie has no bracket; a knockout-only cup has no table).

One competition at a time. A pinned team belongs to its competition: pinning Arsenal in the Premier League does not follow its Champions League matches. Ask another competition for one command with --competition (claudinho --competition champions-league next Arsenal), or set CLAUDINHO_COMPETITION for a shell. Details: the CLI README.

Install

The terminal

npm i -g @claudinho/cli
claudinho follow champions-league --team Arsenal
claudinho today
claudinho today sat            # Saturday's matches (also tomorrow, yesterday, +3)
claudinho next                 # your pinned team's next match, with a countdown
claudinho table
claudinho match <id>           # one match, with its goals and cards

LASK Linz 3–6 Liverpool
  Champions League
  League phase · Raiffeisen Arena (Linz), Linz, Austria
  FT · Kickoff Wed 16:45
  You'll never walk alone!

  22'  ⚽ Goal         LIV  Ronald Araújo
  24'  ⚽ Goal         LIV  Bradley Barcola
  37'  ⚽ Goal         LIV  Bradley Barcola
  51'  ⚽ Goal         LIV  Jeremie Frimpong
  63'  ⚽ Goal         LAS  Robert Ljubicic
  66'  ⚽ Goal         LIV  Bradley Barcola
  72'  ⚽ Goal         LIV  Lewis Koumas
  74'  ⚽ Goal         LAS  Florian Flecker
  77'  ⚽ Goal         LAS  Florian Flecker
  80'  🟨 Yellow card  LAS  Daniel Elfadli

Live data: ESPN
Not affiliated with FIFA, any confederation, league or club, or Anthropic.

This is a capture from Oct 14, 2026. Off the World Cup, match <id> finds a match from yesterday to 14 days ahead, so run it with a current id (claudinho today --json lists each match’s id).

The commands, their options and their --json output: the CLI README. To remove it: claudinho follow off (it deletes the saved choice), then npm rm -g @claudinho/cli, then delete the cache folder (the CLI README says where it is).

Claude Code plugin

The plugin shows the live score (or the countdown to the next match) above your prompt, with the score in bold. A toast says what happened (⚽ GOAL! Liverpool · Ronald Araújo 22' · LASK Linz 0–1 Liverpool, or Full time · LASK Linz 3–6 Liverpool · Liverpool win). When your team scores, and when it wins or draws, Anthropic’s Claude mascot celebrates in the band for a few seconds. With the toasts option set to all, it also celebrates any goal in a match that is not your team’s. /claudinho match opens a pane with the goals and cards. The band, the toasts, the celebration and the pane speak English, Spanish, Portuguese or French (the plugin’s language option). A few fixed words stay English; the plugin README lists them. The capture at the top of this page is the plugin in a real session.

npm i -g @claudinho/cli
claudinho follow champions-league --team Arsenal   # the toasts and the mascot are for your pinned team by default
claudinho init plugin          # only if Claudinho's statusline or hook is in Claude Code's settings

claudinho init plugin removes, from Claude Code’s settings, the statusline whose command is claudinho prompt and the prompt hook whose command is claudinho hook (the commands init claude, init-statusline and init-hook write by default), so the score does not show twice.

Then, in Claude Code in a terminal:

/plugin install claudinho --marketplace arturogarrido/claudinho

While a match is live, the plugin also puts the live score beside each prompt you send, so Claude knows it (from its last reading, when that reading is current and recent). Off-match it adds nothing, and the plugin’s context option turns it off. The plugin reads everything from the installed CLI and never fetches anything itself. Options, the desktop app and the details: the plugin README. To get new versions on their own, turn on auto-update for the claudinho marketplace once (/plugin, the Marketplaces tab, Enable auto-update); Claude Code leaves it off by default for this marketplace. A new version then installs after a session starts, and loads in the next session you start or after /reload-plugins. To remove it: claude plugin uninstall claudinho@claudinho.

The plugin needs @claudinho/cli 0.12.0 or later; with no CLI or an older one it says what to run, as the plugin README says.

Claude Code without the plugin

npm i -g @claudinho/cli
claudinho init-statusline      # the live score under the prompt
claudinho init-hook            # optional: Claude knows the live score during a match

Or both at once, plus the MCP line to run: claudinho init claude. Each command backs up ~/.claude/settings.json first (to settings.json.claudinho.bak, once). Restart Claude Code to see it. To remove both: claudinho init plugin. It removes them when their commands are still claudinho prompt and claudinho hook, and keeps every other setting. Running a local build instead of the global command? init-statusline, init-hook and init-cursor-statusline take --command. From the checkout’s root, after a build: node packages/cli/dist/index.js init-cursor-statusline --command "node \"$PWD/packages/cli/dist/index.js\" prompt".

Cursor CLI

Cursor CLI is Cursor’s agent in the terminal. One command puts the live score in its statusline and prints the MCP config to paste:

npm i -g @claudinho/cli
claudinho init cursor

Restart your agent session to see it. export CLAUDINHO_CURSOR_META=auto adds a second line with the model and the context in use. Prefer to paste the config yourself? claudinho init cursor --print prints it. To remove it: delete the statusLine block from ~/.cursor/cli-config.json (the original is kept as cli-config.json.claudinho.bak). Cursor’s prompt hook cannot pass the score to the model yet, so the score-aware hook is Claude Code only.

MCP server (any agent)

The MCP server gives your agent ten read-only tools, among them today’s matches, live scores, a team’s next match, standings, one match with its goals and cards, and a shareable card. It works in Claude Code, Cursor, Codex, Claude Desktop, Windsurf, Zed, VS Code, and any MCP client that runs a local (stdio) server.

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

Most other clients, Cursor included (~/.cursor/mcp.json), take this config. Some (VS Code, Zed) put the same command and args under a key of their own: see your client’s MCP docs.

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

Then ask mid-task. If you have not run claudinho follow, name the competition in your question.

The tools, the prompts and their fields: the MCP README.

What it does

• Scores, fixtures, standings: today, live, next, table, match <id> with its goals and cards, and bracket for the World Cup. Kickoff times and days are in your timezone (--tz). In a league’s break, an empty today names the next match day (Next match day: Sat 2026-11-21, 4 matches.), and an empty live names the next kickoff.
• Four languages: English, Spanish, Portuguese and French (--lang), with a line of commentary on each match line (¡GOOOOL!) and a team’s own rally cry when it has one (Mexico’s “¿Y si sí?”, Pumas’ “¡Goya!”, Arsenal’s “COYG!”). A postponed or cancelled match gets neither. --flavor off turns it off.
• Clubs and nations: a nation shows with its flag and a club by its name; a nation whose flag no platform draws (Northern Ireland) shows by its name too. No crests, kits or photos.
• Shareable cards: claudinho share next --copy puts a plain-text card for the group chat on your clipboard.
• Prediction-market odds: for World Cup matches, a “who’s favored” line from Polymarket’s public data, shown under today, match and on share cards only when a reliable market exists. Informational only, not betting advice. --no-markets hides it there; claudinho markets asks for the odds on purpose.
• Honest about gaps: when the data provider sends something Claudinho cannot read, the commands and MCP tools that read it, and their share cards, say their data may be incomplete, instead of showing less as if it were all. The statusline and the hook do not.

What stays on your machine

No accounts, no telemetry, no analytics, no Claudinho server. Claudinho asks two public services for data, ESPN for scores and standings and Polymarket for World Cup market odds, with nothing about you attached. The CLI keeps your choice and a small cache on your machine (where); the MCP server writes nothing to disk. The init commands change only the settings file they name, after a one-time backup. Full policy: PRIVACY.md.

FAQ

Do I need an API key or an account? No.

Does it work offline? The World Cup’s schedule ships with the package, so its fixtures work offline. Every other competition’s schedule, and every live score, comes from the network.

Where does the data come from? Scores and standings from ESPN’s public scoreboard (an answer from it says Live data: ESPN), market odds from Polymarket’s public data. Rate limits are respected.

Why no crests, kits or player photos? Claudinho shows facts and emoji flags only (and, in the plugin’s celebration, Anthropic’s Claude mascot). A flag is a nation’s, so a club shows by its name.

Flags show as boxed letters (CH, BA)? Some terminals (Warp, some Windows terminals) cannot draw flag emoji. Claudinho detects Warp and drops the flags: the statusline and bracket show 3-letter codes (MEX), and today, live, next, match, table, team and the hook show plain team names. Share cards keep their flags. Force it anywhere with CLAUDINHO_FLAGS=off, or keep the flags with CLAUDINHO_FLAGS=on.

Around the web

Coverage: LinuxLinks and SuperIsland’s Live Football extension. Listed in the Official MCP Registry, Glama, MCP.so, cursor.directory and awesome-mcp-servers. The full record: PUBLIC_FOOTPRINT.md.

Claudinho stopped publishing a Claude Desktop bundle (.mcpb) to Smithery when Smithery stopped taking updates in October 2026: a bundle installed from there stays at 0.11.1 or older, so switch to npx -y @claudinho/mcp or the Claude Code plugin.

Why star?

Claudinho is a one-person fan project with no budget. If it earns a place in your terminal, a star helps other developers find it and puts new releases in your feed. Want to help build it? CONTRIBUTING.md has the layout, the dev loop and how to propose a change.

Security

Found a vulnerability? Please report it privately through GitHub’s form, not a public issue. SECURITY.md has the process and the threat model.

License

MIT © 2026 Arturo Garrido.

Independent fan project. Not affiliated with FIFA, any confederation, league or club, or Anthropic.

Built while watching the games. #VibingLaVidaLoca ⚽