https://github.com/jedbillyb/claude-bridge
Paper 26.1.2+ plugin that lets Minecraft ops talk to a local Claude Code instance from in-game chat via /claude (async, session-aware, audited).
https://github.com/jedbillyb/claude-bridge
ai anthropic bukkit claude claude-code llm minecraft minecraft-26 minecraft-plugin paper paper-26 paper-plugin pelican-panel rcon spigot
Last synced: about 2 hours ago
JSON representation
Paper 26.1.2+ plugin that lets Minecraft ops talk to a local Claude Code instance from in-game chat via /claude (async, session-aware, audited).
- Host: GitHub
- URL: https://github.com/jedbillyb/claude-bridge
- Owner: jedbillyb
- Created: 2026-06-21T05:55:29.000Z (10 days ago)
- Default Branch: master
- Last Pushed: 2026-06-21T07:10:17.000Z (10 days ago)
- Last Synced: 2026-06-21T08:21:22.056Z (10 days ago)
- Topics: ai, anthropic, bukkit, claude, claude-code, llm, minecraft, minecraft-26, minecraft-plugin, paper, paper-26, paper-plugin, pelican-panel, rcon, spigot
- Language: Java
- Size: 77.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ClaudeBridge
A single Paper plugin (**Paper 26.1.2 and up**, Minecraft calendar versioning)
that lets server ops talk to a local, already-authenticated **Claude Code**
instance from in-game chat via `/claude`. Built against the 26.1.2 stable API.
Requires **Java 25** (Paper 26.1.x's minimum).
Every `/claude ` shells out to the local `claude` binary, captures and
parses its JSON output, and sends the response back into Minecraft chat. Sessions
are kept per-player (in memory) so follow-up questions retain context.
## Build
Requires nothing pre-installed except a JDK to launch Gradle — the wrapper
provisions a JDK 25 toolchain automatically.
```bash
./gradlew build
```
Output jar: `build/libs/ClaudeBridge-.jar`. It bundles no dependencies
(Paper API and Gson are provided by the server at runtime).
## Install
1. Drop the jar in the server's `plugins/` folder and start once to generate
`plugins/ClaudeBridge/config.yml`.
2. Edit `config.yml` (binary path, working directory, timeout, cooldown, etc.).
3. Deploy the `claude-mc-bridge/` folder (CLAUDE.md + rcon.py) to the
`working-directory` configured in step 2.
### Important: this server runs under Pelican/Wings (Docker)
The Paper server — and therefore this plugin's `ProcessBuilder` — runs **inside a
Wings game container**. That has two consequences:
- The `claude` binary must be installed **inside the container's persistent
volume** (`/home/container`), not just on the OCI host. A binary on the host
PATH is not visible to the plugin. Use the **native installer**
(`curl -fsSL https://claude.ai/install.sh | bash`) — the container has no node.
- Headless auth uses a **long-lived OAuth token**: run `claude setup-token` on a
machine you can log in on, then put the token in the file referenced by
`claude-oauth-token-file` (default
`/home/container/claude-mc-bridge/.claude-oauth-token`, mode 0600). The plugin
injects it as `CLAUDE_CODE_OAUTH_TOKEN`. Copying `~/.claude/.credentials.json`
does **not** work — that file is not what authenticates the CLI.
- Console commands: the plugin exposes a localhost, token-guarded HTTP endpoint
(`command-endpoint` in config) and runs commands via RCON internally, returning
their output. Claude calls it with `curl` (no python/node needed). RCON must be
enabled in `server.properties` (the plugin reads `rcon.port`/`rcon.password`
from there automatically). There is no tmux/screen console.
## Command
- `/claude ` — permission node `claudebridge.use` (default: op only).
## Configuration (`config.yml`)
| key | meaning |
|-----|---------|
| `claude-binary` | path to the authenticated `claude` binary |
| `working-directory` | `--cwd` passed to claude; must contain `CLAUDE.md` |
| `allowed-tools` | list passed to `--allowedTools` |
| `timeout-seconds` | kill claude and report a timeout after this long |
| `permission-node` | permission required to run `/claude` |
| `cooldown-seconds` | per-player rate limit between calls |
| `max-response-length` | truncate chat responses past this many chars |
| `log-file` | audit log path (relative → plugin data folder) |
## Audit log
Every invocation is appended to the audit log (`log-file`): timestamp, player,
message, full response, exit code, and duration.
## Extending (Telegram / Discord later)
All Claude logic lives in `ClaudeService` (`invoke(message, resumeSessionId)`),
which has **no Bukkit dependency**. The in-game command handler is a thin caller.
A future Telegram or Discord bot can construct a `BridgeConfig` + `ClaudeService`
and call the same method without touching the command handler.