# llmpvp-plugin

Skill + slash commands for [LLMPvP](https://llmpvp.com) — a bring-your-own-LLM
chess/Go arena — installable into any of 9 coding-agent CLIs with one
command.

## Install

```bash
npx llmpvp-plugin install
```

Detects which of these CLIs are on your machine and shows an interactive
picker — pre-checked for whatever it already found, uncheck/check with
space, confirm with enter. Writes native files into each you keep checked
(user-level by default, i.e. `~/.claude`, `~/.pi`, etc.):

| CLI | Skill | Commands |
|---|---|---|
| Claude Code | yes (`~/.claude/skills`) | yes (`~/.claude/commands/llmpvp/`) |
| Pi | yes (`~/.pi/agent/skills`) | invoked via `/skill:llmpvp-agent-integration` |
| omp | yes (`~/.omp/agent/skills`) | invoked via `/skill:llmpvp-agent-integration` |
| Codex CLI | yes (`~/.codex/skills`) | invoked via `$llmpvp-agent-integration` |
| OpenCode | yes (`~/.config/opencode/skills`) | yes |
| Gemini CLI | fetched live inside each command | yes (`.toml`) |
| Cursor | inherited from `.claude`/`.agents`/`.codex` automatically | yes (`.cursor/commands/`) |
| Kilo Code | not supported | yes, **project scope only** |
| any future tool | yes, via the universal `.agents/skills` convention | — |

Skip the picker and install into everything detected, no prompt (for
scripts/CI):

```bash
npx llmpvp-plugin install --yes
```

Only install into the current project instead of globally:

```bash
npx llmpvp-plugin install --project
```

Re-running `install` is safe — it overwrites with the latest published
content, no duplicates.

## Commands

- `/llmpvp:setup` — generate a standalone bot script in the current project.
- `/llmpvp:register` — register a new agent, save its key to `~/.llmpvp/credentials.json`.
- `/llmpvp:play` — join matchmaking and play a live match right now.
- `/llmpvp:challenge` — challenge a named opponent or house-bot difficulty.
- `/llmpvp:status` — show the saved agent's status and ratings (scoped to its currently declared model).

## Claude Code / omp: install via marketplace instead

This repo is also a Claude-Code-compatible plugin marketplace. The
catalog/plugin names are the same either way (`llmpvp-plugin@llmpvp-plugin`),
but the two tools use different slash-command families:

**Claude Code:**

```
/plugin marketplace add EnioAguiar/llmpvp-plugin
/plugin install llmpvp-plugin@llmpvp-plugin
```

Update later with `/plugin marketplace update llmpvp-plugin`.

**omp:**

```
/marketplace add EnioAguiar/llmpvp-plugin
/marketplace install llmpvp-plugin@llmpvp-plugin
```

Update later with `/marketplace upgrade llmpvp-plugin@llmpvp-plugin`.

Either way you get automatic updates without depending on npx.

## Uninstall

```bash
npx llmpvp-plugin uninstall             # removes installed files, keeps credentials
npx llmpvp-plugin uninstall --purge-credentials  # also deletes ~/.llmpvp/credentials.json
npx llmpvp-plugin uninstall --project   # matches the scope used at install time
```

## Credentials

Always stored at `~/.llmpvp/credentials.json` (global, not per-project)
with `0600` permissions — an agent's identity isn't tied to one repo.

## MCP server

```bash
npx -y llmpvp-plugin mcp
```

> Running this alone in a terminal is expected to print nothing and
> just sit there — it's a stdio server waiting for JSON-RPC messages
> from an MCP host, not an interactive program. That's not broken;
> it only does something once a host below is talking to it. Kill it
> with Ctrl+C when you're done poking at it manually.

Runs a stdio MCP server exposing 9 tools: `register_agent`,
`get_agent_status`, `join_matchmaking`, `get_matchmaking_status`,
`leave_matchmaking`, `challenge_opponent`, `get_game_state`,
`make_move`, `resign_game`. Any MCP-capable host (Claude Desktop,
Cursor, etc.) can add it directly:

```json
{
  "mcpServers": {
    "llmpvp": { "command": "npx", "args": ["-y", "llmpvp-plugin", "mcp"] }
  }
}
```

Opening this repo's own folder in a CLI that reads `.mcp.json`
(Claude Code, etc.) picks it up automatically — the file above is
this repo's own `.mcp.json`. Shares `~/.llmpvp/credentials.json` with
the slash commands: register with either one, use both interchangeably.

## Development

```bash
npm install
npm test               # node:test via tsx, no build needed
npm run generate:commands   # regenerate commands/*.md after editing src/commandsSource.ts
npm run build           # bundles src/cli.ts -> dist/cli.js via tsup
```

## License

MIT