FBM — AI Front Office for Yahoo Fantasy Basketball

Get your own copy: click Use this template (a clean copy under your account), Fork (if you want to send improvements back), or simply git clone it. Your personal league data never lives in the repo, so any of the three works.

FBM turns the AI agent you already use (GitHub Copilot, Claude Code, Codex, Cursor, Gemini CLI, or any MCP-capable agent) into a general manager for one Yahoo Fantasy Basketball league. A deterministic Python engine does all the math — player values, projections, matchup simulations, lineups, streaming, waivers, trades — and exposes it to your agent as tools. The AI reasons over those numbers, drafts proposals, has them independently reviewed, and asks for your approval. FBM never changes your league: it gives you insights, recommendations and proposals, and you make every move in Yahoo yourself. Everything runs on your machine.

Fantasy data provided by Yahoo Fantasy. Not affiliated with Yahoo, ESPN, or the NBA.

Who it's for

• Yahoo Fantasy Basketball managers in a head-to-head categories league who want daily, data-driven help.

• People comfortable running a few terminal commands and using an AI coding agent.

• Anyone who wants to read, audit, or extend a fantasy-basketball analytics engine.

Related MCP server: Yahoo Fantasy MCP

What it does

• Values players with G-scores (a variance-aware improvement on Z-scores) and punt-aware rankings.

• Projects players from this season, last season, recent form, minutes trends, and injury status.

• Simulates your matchup (Monte Carlo, including stats already banked this week) for per-category win odds.

• Recommends the daily lineup and IL moves with exact steps, respecting tip-off locks.

• Plans streaming adds/drops within your weekly add limit.

• Decides rolling waivers: claim now, wait for free agency, or pass.

• Evaluates and finds trades for both sides; compares punt builds; looks ahead to the fantasy playoffs.

• Scouts opponents from league transactions.

• Learns: grades past decisions and checks how well-calibrated its simulations are.

• Drafts: board, live recommendations (with live Yahoo draft sync), and mock drafts.

• Runs on a schedule (optional) and keeps a local memory of strategy, playbook, and journal.

Interfaces: an MCP server (50 tools), the fbm CLI, and a local Streamlit dashboard (14 pages).

What it doesn't do (limitations)

• League formats: Yahoo NBA only; H2H Categories or H2H Most Categories; standard 9-cat (FG%, FT%, 3PM, PTS, REB, AST, STL, BLK, TO) or a subset of them; redraft; rolling waivers.

• Not supported: points or rotisserie leagues; extra or different categories (e.g. DD, TD, OREB, A/T, FTM); FAAB bidding; keeper/dynasty valuation; more than one league per install; ESPN, Sleeper, Fantrax, or other platforms.

• FBM never changes your league. It has no Yahoo write access by design. Lineups and approved moves come back as exact steps you perform in Yahoo yourself.

• Yahoo API access is gated. Since mid-2026 every user must apply for access, which reportedly takes weeks. Until then FBM runs on a realistic demo league (see docs/yahoo.md).

• Unofficial data sources. NBA data comes from public, undocumented ESPN endpoints that may change or break.

• Platforms: developed and tested on Windows. macOS and Linux run in CI but are less battle-tested.

• No guarantees. Projections, simulations, and AI judgement can be wrong. You make the final call.

Requirements

• Python 3.12+ and uv

• git

• An MCP-capable AI agent (see Supported agents)

• For your real league: a Yahoo Fantasy Basketball league and approved Yahoo Fantasy Sports API access (the demo league needs neither)

Quick start

git clone https://github.com/quinjan/basketball-fantasy-manager.git
cd basketball-fantasy-manager
uv sync

Then either:

• Let your agent do it: open your AI agent in this folder and ask it to "set up FBM". It follows the setup-fbm skill, asks one question at a time (agent, models, time zone, automation), and runs the setup for you.

• Do it yourself: uv run fbm setup (interactive; re-run any time, or uv run fbm setup --check to verify).

Setup writes your local settings, seeds your memory folder, loads NBA data, generates your agent's files, and runs health checks. The demo league works immediately. Connect your Yahoo league later, once access is approved — see docs/yahoo.md.

Open the GM office: start a session with your agent in this folder using the gm role and talk to it: "How's my matchup?", "Should I drop X for Y?", "What's pending?", "Approve P-12". Or browse the dashboard with uv run fbm dashboard.

Supported agents

uv run fbm agent install --agent <name> generates everything from the agent-neutral sources in agents/.

Any agent can also use agent-app mode if its app supports scheduled prompts, or none. Details, safety flags, and switching agents: docs/agents.md.

How decisions work

FBM produces three kinds of output — nothing is automatic:

• Insights: read-only analysis (rankings, matchup odds, simulations, opponent intel, health).

• Recommendations: the daily lineup / IL plan with exact steps. You set it in Yahoo; no approval needed. Tell the GM it's done (or uv run fbm lineup --done).

• Proposals: add/drop, waiver claims, trades and strategy changes:

engine numbers → GM proposal → reviewer verdict → your approval → re-validation → exact steps → you do it in Yahoo → you confirm

• Engine numbers: every stat, projection, and probability comes from an engine tool. The AI never does math in its head.

• GM (your best model) drafts a proposal. A reviewer checks it independently — ideally a different model family; on single-vendor agents it is a fresh-context reviewer of the same family, which is a weaker check.

• You approve in chat (your exact words are recorded) or with uv run fbm proposals approve P-12. Unapproved proposals expire.

• Re-validation: after approval the move is checked again against the current league state, then FBM gives you the exact steps (fbm proposals approve prints them; uv run fbm proposals steps P-12 shows them again). Strategy proposals only change FBM's memory and are recorded directly.

• You confirm when it's done (uv run fbm proposals done P-12 --note "..."); the next Yahoo snapshot verifies it. In the demo league, your confirmation is what updates the demo roster.

• Scheduled runs only produce insights, recommendations and proposals; they never act or approve.

Privacy & security

• Your personal state stays on your machine and is gitignored: memory/ (strategy, playbook, journal, manager notes), reports/, data/ (database, caches, snapshots, backups), and config/settings.toml plus other personal config. uv run fbm backup zips it to a local folder.

• Secrets (Yahoo keys and tokens, optional Gmail app password) live in your OS credential store via keyring (Windows Credential Manager, macOS Keychain, Linux Secret Service) — never in files.

• FBM sends nothing anywhere except: requests to Yahoo and ESPN for data, optional Gmail notifications, and what your chosen AI agent sends to its own model provider.

See SECURITY.md to report a vulnerability.

Costs

FBM itself is free. AI usage is billed through your agent's plan; scheduled AI jobs use more of it (engine-only automation uses none). Scheduled jobs only run while your computer is on.

Updating

git pull
uv sync
uv run fbm agent install   # refresh generated agent files
uv run fbm setup --check

Your personal state is gitignored, so pulls don't conflict with it. Want a change in the core engine or prompts? Open a pull request (see CONTRIBUTING.md).

Documentation

• docs/commands.md — every CLI command

• docs/mcp-tools.md — every MCP tool

• docs/analytics.md — how the numbers are made

• docs/agents.md — per-agent setup, roles, models, automation

• docs/yahoo.md — getting Yahoo access and connecting your league

• docs/architecture.md — how the pieces fit together

• AGENTS.md — operating rules every AI agent follows in this repo

Contributing

Bug reports, league-format requests, and pull requests are welcome. Read CONTRIBUTING.md first; run uv run pytest -q and uv run ruff check src tests before submitting.

License

MIT

Disclaimer

FBM is a personal, non-commercial project, not affiliated with or endorsed by Yahoo, ESPN, or the NBA. Use it in line with Yahoo's API terms and each data source's terms. It comes with no warranty: projections and AI recommendations can be wrong, and you are responsible for your roster decisions.