Cricket captaincy is not just "pick the best bowler." It is matchups, dew, field dimensions, batter psychology, bowler workload, Impact Player timing, and the courage to make a call before the obvious moment arrives.
Captain Cool is my attempt to turn that into an agentic AI system: a virtual IPL captain that reads the match state, runs an internal dugout debate, and returns the next tactical decision in cricket language.
The stack is intentionally Google-first:
- Next.js frontend and API routes
- Gemini via
@google/genai - Model:
gemini-2.5-flash - Gemini function calling for tools
- CricAPI / CricketData live score integration
- Free no-key Cricbuzz-backed fallback endpoint
- Custom multi-agent orchestration
The multi-agent loop is custom TypeScript orchestration, but the tool use is real Gemini function calling.
What Captain Cool Does
The user enters or fetches the current match state:
- innings, over, ball
- score and wickets
- striker and non-striker
- bowling resources
- pitch condition
- dew factor
- venue
- target / required rate
- Impact Player availability
- optional live match ID or URL
Captain Cool replies with:
- the next captaincy decision
- cricket-language reasoning
- visible dissent from the Devil's Advocate agent
- confidence score
- counterfactual
- full debate transcript
Example output:
Captain's Call:
BOWL PATHIRANA - OVER 16
Why:
The wet ball has taken Jadeja's grip away. Pathirana's skiddy angle
is harder for Tilak to get underneath, and the field protects the
midwicket release shot.
Dissent:
The risk is burning Pathirana before the 18th. If this over leaks 14,
the death plan gets thin.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Next.js UI │
│ Premium cricket broadcast dashboard │
│ Manual match state + live match fetch + agent debate view │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Next.js API Routes │
│ │
│ /api/strategy │
│ /api/cricket/current │
│ /api/cricket/match?id=... │
│ /api/cricket/free-score?match=... │
│ /api/live-matches │
│ /api/live-strategy │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Gemini Agent Orchestrator │
│ │
│ 1. Stats Analyst │
│ ├─ fetchLiveMatchData tool, when match ID is present │
│ └─ calculateMatchPressure tool │
│ │
│ 2. Tactical Strategist │
│ └─ proposes first captaincy call │
│ │
│ 3. Devil's Advocate │
│ └─ challenges the plan │
│ │
│ 4. Tactical Strategist │
│ └─ defends or revises │
│ │
│ 5. Match Commentator │
│ └─ formats fan-friendly final answer │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ UI Result │
│ Captain's Call + Why + Dissent + Confidence + Debate │
└─────────────────────────────────────────────────────────────┘
Agent Design
The system uses four named Gemini-powered agents. Each agent is a separate Gemini call with its own system prompt and role.
1. Stats Analyst
The Stats Analyst does not make tactical decisions. It reads numbers, phase, pressure, match conditions, and live data.
Prompt excerpt:
You are a world-class cricket statistician — think of ESPNcricinfo's
StatsGuru merged with a baseball sabermetrician.
YOUR IDENTITY:
- You speak in numbers, trends, and matchups ONLY
- You NEVER suggest a decision or give an opinion
- You respond to queries with structured statistical evidence
- Every claim must include a number: average, strike rate, economy,
sample size, historical trend
- If a CricAPI live match ID is present in the match state, your FIRST
action must be calling fetchLiveMatchData before any analysis.
Output shape:
STATISTICAL BRIEF:
• Matchup
• Venue Trend
• Phase Analysis
• Condition Factor
• Historical Parallel
2. Tactical Strategist
The Strategist is the captaincy brain. It makes the first call: who bowls, how the field is set, whether to use the Impact Player, when to take the timeout, and what the contingency is.
Prompt excerpt:
You are the tactical brain of an IPL captaincy team. Think MS Dhoni's
instinct + Rohit Sharma's bowling changes + Hardik Pandya's aggression.
YOUR IDENTITY:
- You make BOLD, specific tactical decisions
- You think 2-3 overs ahead, not just the next ball
- You understand cricket psychology, momentum, and pressure
- You're not afraid to use unorthodox options
Output shape:
TACTICAL DECISION:
• Next Bowler
• Field Setup
• Batting Move
• Impact Player
• Strategic Timeout
• Contingency
TACTICAL LOGIC:
...
3. Devil's Advocate
This agent exists to disagree. It challenges the Strategist's first plan with the kind of objection an assistant coach would raise in a real dugout.
Prompt excerpt:
You are the cautious inner voice of a cricket captain — the part
that asks "what if this goes horribly wrong?" before every decision.
YOUR IDENTITY:
- Your job is to FIND FLAWS in every tactical proposal
- You think about WORST-CASE SCENARIOS
- You remember cricket history where similar decisions backfired
- You are NOT negative — you are rigorous.
Critique framework:
1. Matchup counter
2. Resource mismanagement
3. Condition misread
4. Psychological backfire
5. Historical precedent
6. Opportunity cost
4. Match Commentator
The Commentator turns the internal debate into something a non-technical fan can enjoy.
Prompt excerpt:
You are the voice of cricket — imagine Harsha Bhogle's storytelling
meets Ravi Shastri's energy meets Ian Bishop's gravitas.
YOUR IDENTITY:
- You translate complex tactical decisions into ELECTRIC commentary
- You make cricket strategy accessible to a 12-year-old fan
- You capture the DRAMA, the tension, the "what if"
- You speak like you're on live television
Final output:
CAPTAIN COOL'S CALL
THE COMMENTARY
THE DUGOUT DEBATE
CONFIDENCE METER
Gemini Function Calling
Captain Cool uses Gemini function calling for real tool use. The two important tools are:
Tool 1: fetchLiveMatchData
This tool fetches live match information before analysis when a live match ID or URL is available.
Schema:
export const fetchLiveMatchDataTool: FunctionDeclaration = {
name: "fetchLiveMatchData",
description:
"Fetch live match score, status, teams, venue, scorecard, and innings details. Prefer CricAPI match IDs; also accepts a Cricbuzz URL or numeric match ID through a free no-key fallback.",
parameters: {
type: Type.OBJECT,
properties: {
matchId: {
type: Type.STRING,
description: "A CricAPI match ID, Cricbuzz match ID, or Cricbuzz live match URL.",
},
},
required: ["matchId"],
},
};
Handler:
export async function handleFetchLiveMatchData(args: {
matchId?: string;
}) {
if (!args.matchId) {
return { error: "Missing live match ID or URL." };
}
try {
if (!/^https?:\/\//i.test(args.matchId) && process.env.CRICAPI_KEY) {
return await getLiveCricketMatchDetails(args.matchId);
}
} catch {
// Fall through to the free no-key provider.
}
return await getFreeLiveCricketScore(args.matchId);
}
Tool 2: calculateMatchPressure
This local tool converts match state into tactical context.
It calculates:
- current over
- balls remaining
- innings phase
- current run rate
- required run rate
- runs needed
- pressure score
- pressure label
- bowler overs remaining
- tactical flags
Example output:
{
"phase": "death",
"currentRunRate": 9.16,
"requiredRunRate": 9.78,
"pressureScore": 72,
"pressureLabel": "high",
"tacticalFlags": [
"Death-over specialists and boundary protection take priority.",
"Dew reduces grip, so yorkers, hard lengths, and pace-off cutters become safer than big spin."
]
}
Orchestration Flow
The orchestration is intentionally multi-turn:
Step 1:
Stats Analyst checks if liveMatchId exists.
If yes, Gemini calls fetchLiveMatchData.
Step 2:
Stats Analyst calls calculateMatchPressure.
Step 3:
Stats Analyst summarizes tactical context.
Step 4:
Tactical Strategist proposes the first plan.
Step 5:
Devil's Advocate challenges the plan.
Step 6:
Tactical Strategist defends or revises.
Step 7:
Match Commentator converts the whole debate into final fan-facing JSON.
The important bit: this is not one Gemini call pretending to be multiple agents. Each role is a separate Gemini request with its own prompt and context.
Real-Time Data
Captain Cool supports three live-data paths:
1. CricAPI / CricketData
Used for current match lists and detailed scorecards.
Routes:
GET /api/cricket/current
GET /api/cricket/match?id=<match-id>
Environment variable:
CRICAPI_KEY=...
2. Free No-Key Fallback
For quick demos without a key, the app can fetch from a Cricbuzz-backed JSON endpoint.
Route:
GET /api/cricket/free-score?match=<id-or-url>
This accepts:
- Cricbuzz numeric match ID
- Cricbuzz live match URL
3. SportMonks
SportMonks is available as a richer live source when a token is present.
Routes:
GET /api/live-matches
POST /api/live-strategy
Environment variable:
SPORTMONKS_API_TOKEN=...
UI Design
I wanted the interface to feel like a premium cricket broadcast truck, not a generic chatbot.
The dashboard includes:
- dark navy broadcast-studio theme
- pitch green and gold accents
- scoreboard-style match state
- live match ticker
- pitch visualization
- field placement diagram
- agent debate bubbles
- confidence gauge
- live metrics sparklines
- "Ask Captain" action button
- "Free Fetch" live-score fallback
The UI sections are:
Top Bar:
THE DUGOUT, AI status, match clock, ticker
Left Panel:
Match state, scoreboard, pitch, batters, bowlers
Center Panel:
Live score fetcher, Captain's Call, controls
Right Panel:
Agent debate and confidence meter
Bottom:
Live metrics
End-to-End Walkthrough
Scenario:
Match: CSK vs MI at Chepauk
Innings: 2
Score: 142/4
Overs: 15.3
Target: 186
Striker: Tilak Varma, 47* off 31
Non-striker: Hardik Pandya, 12* off 8
Pitch: turning
Dew: setting in
Impact Player: available
Strategic Timeout: available
Step 1: Fetch Live Data
The user can either:
- click "Fetch Current" with a CricAPI key
- paste a Cricbuzz match ID or URL and click "Free Fetch"
The dashboard renders:
MI 142/4
15.3 overs
Target 186
Required rate around 9.8
Status: Live
Step 2: Ask Captain
The user clicks:
ASK CAPTAIN
The four-agent spinner starts:
Stats Analyst
Strategist
Devil's Advocate
Commentator
Step 3: Stats Analyst Tool Calls
If a live match ID is present:
fetchLiveMatchData(matchId)
Then:
calculateMatchPressure(matchState)
The Stats Analyst returns something like:
• Phase Analysis: Over 15.3 means the match is entering the death phase.
• Required Rate: MI need 44 from 27 balls, about 9.78 RPO.
• Condition Factor: Dew reduces grip, so spin is less reliable.
• Resource View: Pathirana has one high-leverage over available.
Step 4: Strategist Makes the First Call
The Strategist proposes:
Bowl Pathirana for over 16.
Set deep midwicket, long-on, long-off, deep square.
Keep fine leg up and protect the hard-length release shot.
Hold the Impact Player unless a wicket falls.
Step 5: Devil's Advocate Pushes Back
The Devil's Advocate challenges:
If Pathirana leaks 12-14 now, CSK lose their death-over cushion.
Jadeja has completed his quota, so the fallback death plan becomes thin.
The wet ball could turn yorkers into low full tosses.
Step 6: Strategist Revises or Defends
The Strategist responds:
Proceed with Pathirana, but bowl over the wicket to Tilak.
If the first two balls go for boundaries, switch the plan next over:
hard-length pace-off into the pitch, not spin.
Step 7: Commentator Finalizes
The final answer becomes:
CAPTAIN'S CALL:
BOWL PATHIRANA - OVER 16
WHY:
The dew has made spin risky. Pathirana's skiddy angle is the better
weapon against a set left-hander. The field protects Tilak's strongest
release shot and asks him to hit to the bigger, weaker zone.
DISSENT:
The dugout worry is resource burn. If this over goes badly, the 18th
and 20th over plan gets uncomfortable.
CONFIDENCE:
78%
AI Studio Prompt Link
I prototyped prompts locally in code during the build. I have not published a Google AI Studio prompt link yet.
Before publishing the final dev.to post, add it here:
Final Thought
A massive shoutout to ** @gdgcloudpune , especially *@antrixsh_gupta *, *@pratik_kale *, and the entire organizing team. The problem statement was brilliant, the vibe was electric, and events like this push the developer community to level up in incredible ways.
👇 Check out the code and try it yourself:
GitHub Repository: https://github.com/swamiabhishek45/captain-cool
Live Link : https://captain-cool-dusl.vercel.app/