Sleeper Caffeine

Sleeper Caffeine is an open-source, read-only fantasy football front office for the desktop. Connect a public Sleeper league, choose your roster, and use Codex to produce league-specific analysis grounded in live Sleeper data and current web research.

The first release is intentionally safe: it cannot change a lineup, submit a waiver claim, send a trade, or accept one.

What works today

• Multi-league onboarding from a Sleeper league URL or ID.

• Team selection with Sleeper names, avatars, roster IDs, and user IDs.

• A polished dashboard, full roster room, reserve/taxi handling, headshots, and fallbacks.

• Manual Sleeper refresh with an immutable local snapshot history.

• A live draft board with completed picks, traded ownership, upcoming slots, and a deterministic candidate baseline.

• Optional 15-second draft-room polling, positional-run and tier signals, candidate pins, and board-change explanations without an AI turn.

• Board-bound Caffeine Plans with researched rankings, fallbacks, lifecycle states, and a preserved final-board archive.

• A regular-season Weekly Command Center built around one durable league/week plan rather than disconnected reports.

• An explicit Tuesday Build my plan pass with competitive lane, waiver contingencies, Add/Watch/Exit, roster-purpose audit, alternatives, trade-market observation, sources, and a decision checklist.

• A zero-AI Wednesday aftermath, plus focused manager-triggered Thursday lineup and weekend execution briefings.

• Persistent action dispositions, immutable plan/brief history, evidence freshness, material-change reconciliation, and draft-to-Week-1 watchlist handoff.

• On-demand AI cards for team analysis and trade ideas.

• A persistent conversational analyst scoped to the active league.

• Live web research with an explicit distinction between search/discovery and cited sources.

• A standalone Sleeper MCP server over stdio and an app-managed Streamable HTTP bridge.

Related MCP server: sleeper-mcp

Product principles

1. League data first. Codex must read the Sleeper MCP before making league-specific claims.

2. Refresh is deterministic. Refreshing Sleeper updates SQLite and invalidates stale reports; it never spends an AI turn.

3. AI is explicit. Every report has its own Generate or Regenerate action.

4. Search is not a source. Search discovers material. Reports cite the page actually used.

5. Read-only means read-only. No Sleeper credentials, browser cookies, shell access, or hidden roster mutations.

6. Local by default. League snapshots, reports, recommendation history, chat, and the isolated Codex home live on the user's machine.

7. One evolving weekly plan. Tuesday, Wednesday, Thursday, and the weekend share one persisted league/week context and never silently rewrite the manager's decisions.

Architecture

flowchart LR
    Renderer["Electron renderer"] -->|typed IPC| Main["Electron main process"]
    Main --> Store["SQLite snapshots + plans + evidence + decisions"]
    Main --> Core["sleeper-core"]
    Main --> Codex["Installed codex app-server"]
    Codex -->|Streamable HTTP| MCP["Sleeper MCP bridge"]
    MCP --> Core
    Core --> API["Sleeper public API"]
    Core --> Cache["24-hour player cache"]
    Codex --> Web["Live web search"]

The renderer is sandboxed and receives only a narrow preload API. It never receives OpenAI tokens, raw child-process access, SQLite access, or arbitrary filesystem primitives.

Codex runs as one long-lived codex app-server process with:

• A dedicated CODEX_HOME inside the app's user-data directory.

• Codex-managed ChatGPT OAuth.

• A read-only sandbox and approvalPolicy: "never".

• The shell tool disabled.

• Live web search enabled.

• The local Sleeper MCP configured automatically.

Sleeper Caffeine discovers Codex through CODEX_CLI_PATH, the user's PATH, or known Codex/ChatGPT application locations. It does not bundle a Codex binary.

Repository layout

apps/
  desktop/                 Electron + React desktop product
packages/
  sleeper-core/            Sleeper API, schemas, joins, cache, domain logic
  sleeper-mcp/             Standalone MCP plus stdio and HTTP transports
  ipc-contract/            Renderer/main schemas and typed API
  codex-runtime/           Binary discovery, JSONL RPC, OAuth, threads, turns

The desktop and MCP use the same sleeper-core; the UI never calls the MCP as an internal API.

The React renderer is organized around an internal design system and feature slices:

renderer/
  app/            providers, query cache, runtime events, shell
  api/            sole typed preload/IPC client and data hooks
  components/ui/  reusable internal primitives and CSS Modules
  features/       onboarding, assistant, draft, weekly, reports, roster, settings
  styles/         semantic tokens, reset, and global Electron chrome

Canonical renderer state uses TanStack Query with explicit IPC mutations. Runtime events update or invalidate that cache; assistant-ui continues to own partial chat streaming. See the renderer conventions before adding a UI surface.

Desktop chrome, minimum-window behavior, mutable application paths, and the native macOS/Windows/Linux smoke checklist are documented in platform validation.

Requirements

• Node.js 22 or newer.

• pnpm 10.

• An installed Codex CLI or an application that ships the Codex binary.

• A ChatGPT account for AI analysis. Sleeper browsing and roster views work without it.

Run locally

pnpm install
pnpm dev

Production build:

pnpm build
pnpm --filter @sleeper-caffeine/desktop test:browser
pnpm --filter @sleeper-caffeine/desktop storybook:build

After packaging for the current platform, exercise the packaged preload, migrations, navigation, and native chrome:

pnpm --filter @sleeper-caffeine/desktop test:smoke:packaged

Package the current platform:

pnpm dist:mac
pnpm dist:linux
pnpm dist:win

The app is not yet signed or notarized. Local macOS builds may require the standard unsigned-app development workflow.

Standalone Sleeper MCP

The original adapter remains independently usable:

pnpm build:packages
pnpm --filter @sleeper-caffeine/mcp start

Example Codex CLI registration:

codex mcp add sleeper -- node /absolute/path/to/sleeper-caffeine/packages/sleeper-mcp/dist/src/index.js

Tools:

Sleeper's player directory is cached for 24 hours. “Available” means absent from current rosters; it does not prove waiver clearance or lineup eligibility.

Development checks

pnpm typecheck
pnpm lint
pnpm test
pnpm build

Read-only live checks are opt-in:

SLEEPER_LIVE_LEAGUE_ID=123456789012345678 \
SLEEPER_LIVE_USER=your_username \
pnpm test:live

The desktop also contains opt-in live coverage for onboarding and the Codex app-server handshake.

Data and privacy

• Sleeper's documented fantasy API is public and read-only; no Sleeper password is requested.

• ChatGPT login is managed and stored by Codex inside the app-specific CODEX_HOME.

• OpenAI access and refresh tokens are never exposed to the renderer or stored in SQLite.

• “Clear local league data” removes leagues, snapshots, reports, chats, thread references, and the player cache. It deliberately does not sign the user out of ChatGPT.

• The Athletic may appear in public search results, but this release does not automate a signed-in browser or bypass a subscription wall.

See SECURITY.md for reporting and trust boundaries.

Roadmap

• Historical recommendation calibration and richer retrospective scoring.

• Additional projections/rankings adapters with clear licensing boundaries.

• Tray/background scheduling and opt-in notifications only after the pull-based experience is proven.

• Cross-platform release signing and auto-update infrastructure.

• Any future Sleeper write automation only as a separately designed, opt-in capability with explicit confirmations.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md, and keep every proposed Sleeper integration read-only unless a future design document explicitly changes that boundary.

Sources

• Sleeper API documentation

• Model Context Protocol TypeScript SDK

• OpenAI Codex app-server documentation

License

MIT