ValoDesk

A conversational CLI agent for VCT (Valorant Champions Tour) esports questions. Ask about upcoming matches, a team's map stats, head-to-heads, or regional player leaderboards from your terminal.

You: What's G2's record on Ascent?
Agent: G2's record on Ascent is as follows:
- Total games: 41
- Wins: 26
- Losses: 15
- Win percentage: 63%

How it works

• An LLM-based agent (LangGraph + GPT-4o-mini) decides which tool to call based on your question.
• Tools are served over MCP (Model Context Protocol) by a local server process, which wraps a data client hitting vlrggapi (an unofficial vlr.gg API wrapper).
• Conversations are stored locally in SQLite, so follow-up questions like "and on Bind?" work without repeating context.
• Previous conversations can be listed and resumed even after closing ValoDesk.

Requirements

• Python 3.11+
• Your own OpenAI API key

Install

pipx install valodesk

valodesk talks to a hosted vlrggapi instance (an unofficial vlr.gg API wrapper).

First run

valodesk <your-openai-api-key>

This saves your key to ~/.valodesk/.env. Every run after that, just:

valodesk

Conversation history

ValoDesk stores conversations locally in a SQLite database at:

~/.valodesk/history.db

The following commands are available inside the CLI:

Command	What it does
/new	Start a new conversation
/list	List saved conversations
/resume	Select and continue a previous conversation
quit	Exit ValoDesk

If you ask a question without starting or resuming a conversation, ValoDesk automatically creates a new one. The first question is used as its title.

Database schema

Conversations

Column	Type	Purpose
id	INTEGER	Unique ID for the conversation
created_at	TEXT	When the conversation was created
title	TEXT	Title taken from the first question

Messages

Column	Type	Purpose
id	INTEGER	Unique ID for the message
conversation_id	INTEGER	Conversation the message belongs to
role	TEXT	Whether the message came from the user or assistant
content	TEXT	The message itself
created_at	TEXT	When the message was created

Each conversation can contain multiple messages, and ValoDesk uses conversation_id to load them in order whenever the user resumes that chat.

Tools available

Tool	What it answers
get_matches	Upcoming matches, optionally for one team, optionally limited to N results
get_map_stats	A team's win/loss record on one map, or every map
get_h2h	Past matches between two specific teams
get_region_stats	A region's player stats leaderboard, optionally for one team's players

Known limitations

• get_matches only sees roughly the next week of scheduled matches (a limitation of the upstream API's "upcoming" query, which doesn't support pagination).
• Resumed conversations currently send their full message history back to the model, so very long conversations may increase token usage.

Credits

All match/stats data comes from vlrggapi by axsddlr.