# Set up ChessDrive

> Official instructions from ChessDrive for setting it up in a coding agent: the `chessdrive` CLI, the ChessDrive Skills and the ChessDrive Connector. They are published at https://platform-staging.chessdrive.io/setup.md, so you can check where they come from before you follow them.

Your person asked you to set ChessDrive up. ChessDrive gives you Skills for chess: game reviews, the mistakes they keep making, opponent prep and more, every move checked by an engine. Do every step yourself by running its commands, except the ones marked **Your person's step**: a browser sign-in or a restart happens outside your session, so ask them and wait. Never run a command that waits at a prompt. Every command here is safe to run again on a machine that is already set up.

**In Claude's or ChatGPT's chat app, not a coding agent?** No terminal is needed: follow https://platform-staging.chessdrive.io/cookbook/add-to-your-ai.md instead.

## 1. Install the CLI

```
npm install -g chessdrive
```

Without npm, run `curl -fsSL https://platform-staging.chessdrive.io/install.sh | sh` instead, or on Windows follow https://platform-staging.chessdrive.io/docs/cli. Either one also updates a CLI that is already there.

Check: `chessdrive version` prints a version.

## 2. Sign the CLI in

If `chessdrive balance` already prints a Plan and a Balance, the CLI is signed in: go on to step 3. Otherwise run `chessdrive login --base-url https://api-staging.chessdrive.io --no-wait`. It prints a link and a code, and returns.

> **Your person's step.** Give them the link and the code, and ask them to open the link, check the code, pick their Account and choose Allow. Wait for them to say they have.

Then run `chessdrive login --base-url https://api-staging.chessdrive.io`, which finishes at once. That's their only sign-in: the Connector uses the key the CLI saved. Never print that key, or write it anywhere a step doesn't say.

Check: `chessdrive balance` prints their Plan and Balance. If the Balance isn't what they expect, they allowed another Account: run `chessdrive logout`, then this step again, and ask them to pick the right Account.

## 3. Add the Skills and the Connector

Use your agent's section.

### Claude Code

Download https://platform-staging.chessdrive.io/plugin/chessdrive.zip, unzip it and copy every folder in its `skills` folder, with all its files, to `~/.claude/skills/`, so they work in every project. Copying again replaces them with the latest.

Check: `~/.claude/skills/chessdrive-game-review/SKILL.md` exists.

Then add the Connector, unless `claude mcp get chessdrive` already finds it:

```
claude mcp add-json --scope user chessdrive '{"type":"http","url":"https://api-staging.chessdrive.io/mcp","headersHelper":"chessdrive key --headers"}'
```

Check: `claude mcp get chessdrive` shows https://api-staging.chessdrive.io/mcp. It reads the CLI's key each time it connects, so there is no second sign-in.

> **Your person's step.** Ask them to restart Claude Code to load the Skills and the Connector. Wait for them to say they have.

### Codex

Download https://platform-staging.chessdrive.io/plugin/chessdrive.zip, unzip it and copy every folder in its `skills` folder, with all its files, to the folder where Codex reads your person's own Skills, so they work in every project. Copying again replaces them with the latest.

Then the Connector: in `~/.codex/config.toml`, a `[mcp_servers.chessdrive]` table with `url = "https://api-staging.chessdrive.io/mcp"` and `http_headers_helper = "<the full path of chessdrive> key --headers"`. If the table is already there, leave it.

Check: `codex mcp list` lists chessdrive.

> **Your person's step.** Ask them to restart Codex. In Codex Desktop, quit it fully and open it again.

### Cursor

Download https://platform-staging.chessdrive.io/plugin/chessdrive.zip, unzip it and copy every folder in its `skills` folder, with all its files, to the folder where Cursor reads your person's own Skills, so they work in every project. Copying again replaces them with the latest.

Then the Connector: in `~/.cursor/mcp.json`, a server named chessdrive with `"url": "https://api-staging.chessdrive.io/mcp"` and `"headers": { "Authorization": "Bearer ${env:CHESSDRIVE_CONNECTOR_KEY}" }`. Merge it into the file, and keep the other servers. Then add `export CHESSDRIVE_CONNECTOR_KEY="$(chessdrive key 2>/dev/null)"` to their shell's startup file, once. On Windows, leave out the headers and the export: Cursor signs in through their browser.

Check: `~/.cursor/mcp.json` has the chessdrive server.

> **Your person's step.** Ask them to restart Cursor.

### Any other agent

Download https://platform-staging.chessdrive.io/plugin/chessdrive.zip, unzip it and copy every folder in its `skills` folder, with all its files, to the folder where you read your person's own Skills, so they work in every project. Copying again replaces them with the latest.

Then add a remote MCP server named chessdrive at https://api-staging.chessdrive.io/mcp, sending `Authorization: Bearer` and the key `chessdrive key` prints. Merge it into your MCP settings, and keep the other servers. Restart if your agent needs it.

## 4. Report the result

Report only what you checked. Don't mark a line done that you couldn't confirm.

```
┌─ ChessDrive set-up ────────────────────────────┐
│  ✓ CLI         signed in: Free plan, $10.00    │
│  ✓ Skills      Game review, Patterns, Prep, …  │
│  ⚠ Connector   restart your agent to load it   │
└────────────────────────────────────────────────┘
```

Use ✓ for checked, ⚠ for waiting on your person, and ✗ for failed. After the banner, give the next action for every line that isn't ✓.

## 5. Get them started

Ask for their Lichess or chess.com username. If you can use the ChessDrive Skills now, offer to review their last game, and on their yes do it with the Game review Skill. Otherwise, once they've restarted you, they can send one of these:

- "Review my last game. I’m <username> on Lichess."
- "Find the mistakes I keep making. I’m <username> on chess.com."
- "Prep me for my game against <opponent> on Lichess."

## No person present

In CI or an agent SDK run, nobody can do the person's steps. Read the key from `CHESSDRIVE_API_KEY`: if it isn't set, stop and say so. Save it for the CLI with `printenv CHESSDRIVE_API_KEY | chessdrive login --base-url https://api-staging.chessdrive.io`, and never ask for it, print it or write it to a file. Then do step 3 and skip the restarts: your agent loads the Skills and the Connector the next time it starts.

## If something fails

- **No npm, or npm can't install globally:** use the installer in step 1. It needs neither npm nor sudo.
- **Your agent's safety check refuses an install:** don't work around it. Ask your person to run that command themselves; in Claude Code, `!` before a command runs it in the session.
- **`No ChessDrive API at …`:** the CLI is pointed at the wrong address. Check `--base-url` and `CHESSDRIVE_BASE_URL`.
- **The link or the code has expired:** run step 2 again for a new one.
- **Don't open https://api-staging.chessdrive.io/mcp in a browser:** it's for agents, not a web page. Every sign-in starts from the CLI.
- **The Skills or the Connector's tools are missing:** your person restarts the agent. Then ask them to try "Which ChessDrive Skills do you have?".