# ♞ Nouchess

**English** · [Português (Brasil)](README.pt-BR.md)

Play chess against LLMs. Fully open source (GPL-3.0).

The name comes from *nous* (νοῦς), Greek for "mind" or "intellect".

There are two ways to play:

- **MCP** (available): an agent such as Claude Code, Codex or Antigravity connects to Nouchess over MCP. You move on a web board and talk to the agent in its own chat. No API key needed: the agent runs on the subscription you already have.
- **API** (available): you add an API key (Anthropic, OpenAI, Google AI Studio, NVIDIA NIM, OpenRouter, or any OpenAI-compatible provider) or point Nouchess at a local model (Ollama, LM Studio). You pick a model and play it on the board, with a built-in chat next to it.

## Installation

Requires Node 22.13+ and pnpm.

```bash
git clone https://github.com/denkalli/Nouchess.git && cd Nouchess
pnpm install
pnpm build    # builds the web board
```

## Connecting an agent

### Recommended: stdio

The agent starts Nouchess on its own, so you don't need to keep anything running.

**Claude Code**

```bash
claude mcp add --scope user nouchess -- node /path/to/Nouchess/packages/server/bin/nouchess.js mcp
```

**Codex**: in `~/.codex/config.toml`

```toml
[mcp_servers.nouchess]
command = "node"
args = ["/path/to/Nouchess/packages/server/bin/nouchess.js", "mcp"]
```

Then ask: *"let's play chess on nouchess"* (in Claude Code you can also run `/mcp__nouchess__play`).

How it works:

- Opening an agent session starts **nothing**: the tool list is answered locally by the stdio bridge.
- On the first tool call, the bridge checks whether the server is running. If it isn't, the bridge starts it in the background, detached from the agent, and the board opens in your browser.
- The server keeps running after the agent session ends. It shuts itself down after 30 minutes with no board open and no agent activity (`NOUCHESS_IDLE_EXIT_MIN`).
- Multiple sessions and agents share the same server and the same game.

### Alternative: HTTP

For clients that only speak Streamable HTTP. In this mode the server must be running **before** the agent session starts.

```bash
pnpm start    # starts the server and opens http://localhost:3737
```

```bash
claude mcp add --scope user --transport http nouchess http://localhost:3737/mcp
```

### Development

```bash
pnpm dev      # server in watch mode + UI with hot reload at http://localhost:5173
```

## Playing against a model (API mode)

1. Start Nouchess (`pnpm start`, or let an agent start it) and open **Settings**.
2. Add an API key for a provider, or check that your local Ollama / LM Studio server is running. **Test** lists the models the key can use.
3. In **Play → New game → Model (API)**, pick the provider and model, optionally a reasoning effort, a name and a personality, then start.

Notes:

- Every move (and every chat reply) is a request to the provider and uses your API credits. Token usage is shown per game.
- Keys can also come from environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `NVIDIA_API_KEY`, `OPENROUTER_API_KEY`). Without a key, the Anthropic provider also accepts an `ant auth login` profile.
- Models that don't support tool calling (common with small local models) switch automatically to a plain-text protocol (`MOVE: e4`).
- If the provider fails (network, rate limit, invalid key), the game pauses and shows a **Try again** button.

## How a game works (MCP mode)

```
Agent: make_move("e4") ──► server ──► board updates (WebSocket)
Agent: wait_for_opponent() … blocks …
You:   move a piece on the board ──► wait_for_opponent returns your move
Agent: make_move(...) → wait_for_opponent() → …
```

- `wait_for_opponent` returns "still waiting" every ~45s (`NOUCHESS_WAIT_MS`), because MCP clients abort long-running calls. The agent is told to simply call it again.
- If the agent stops anyway, send anything in its chat ("your move"). It resumes with `get_state`.
- Illegal moves by the agent count: after 3 in the same turn, it forfeits.
- The agent is told **not** to use chess engines. Agents have shell access, so this is an honor rule, not a guarantee.

### MCP tools

| Tool | Description |
|---|---|
| `new_game` | Start a game (choose the agent's color) |
| `get_state` | ASCII board, FEN, recent moves, whose turn it is, legal moves |
| `make_move` | Play a move (SAN or UCI), with an optional comment |
| `wait_for_opponent` | Wait for the human's move |
| `say` | Message shown next to the board |
| `offer_draw` / `respond_to_draw` | Draws |
| `resign` | Resign |

MCP prompt: `play`.

## Project structure

```
packages/core     Game rules and state (chess.js), serialization, LLM rendering, tests
packages/server   HTTP + WebSocket + MCP (HTTP and stdio bridge), SQLite store, settings,
                  provider adapters (Anthropic, OpenAI-compatible) and the API opponent
apps/web          React + Vite + chessground (the Lichess board); English and Portuguese UI
```

Dev helper to act as an agent without an MCP client:

```bash
pnpm --filter @nouchess/server mcp-call make_move '{"move":"e4"}'
```

## Configuration

| Variable | Default | |
|---|---|---|
| `NOUCHESS_PORT` | `3737` | Server port |
| `NOUCHESS_HOST` | `127.0.0.1` | Bind address. Keep it local: the MCP endpoint has no authentication |
| `NOUCHESS_WAIT_MS` | `45000` | Maximum duration of each `wait_for_opponent` call |
| `NOUCHESS_IDLE_EXIT_MIN` | `30` | Idle minutes before a server auto-started by the stdio bridge shuts down |
| `NOUCHESS_OPEN_BROWSER` | `1` | Set to `0` to stop Nouchess from opening the browser on its own |
| `NOUCHESS_HOME` | (per-OS default) | Put the database and settings in this directory instead |
| `NOUCHESS_ALLOWED_HOSTS` | | Extra hostnames (comma-separated) the server accepts besides `localhost` |

## Data and privacy

- **Games** are saved in a SQLite database: `~/.local/share/nouchess/nouchess.db` on Linux, `~/Library/Application Support/nouchess/` on macOS, `%LOCALAPPDATA%\nouchess\` on Windows. An unfinished game resumes after a restart.
- **Settings and API keys** live in `config.json` in `~/.config/nouchess/` (Linux), `~/Library/Application Support/nouchess/` (macOS) or `%APPDATA%\nouchess\` (Windows), with file mode `0600`. Keys are never sent to the browser.
- The server listens on `127.0.0.1` only. It rejects requests whose `Host` isn't local (DNS rebinding) and state-changing requests from other websites' origins.
- Nouchess sends nothing anywhere except to the providers you configure.

## Versioning

Nouchess uses CalVer in the form `YY.MM.PATCH`. For example, `26.11.0` is the first release of November 2026. See the [CHANGELOG](CHANGELOG.md) and the [ROADMAP](ROADMAP.md).

## License

[GPL-3.0-or-later](LICENSE). The board uses [chessground](https://github.com/lichess-org/chessground) (GPL-3.0).