Skip to main content
Glama
README.md
<div align="center">

# 🕹️ Agents Plugins

**The CS Modding marketplace (`csmodding`) of agent plugins for Claude Code and OpenAI Codex CLI.**

Give your coding agent **eyes and hands inside a running game**: its HTML UI, and its C#/ECS
internals.
Generic tooling, developed and verified against Cities: Skylines II.

Encourage my work by putting a star ⭐ if it has been useful to you!

[![CI](https://github.com/CitiesSkylinesModding/agents-plugins/actions/workflows/ci.yml/badge.svg)](https://github.com/CitiesSkylinesModding/agents-plugins/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/%40csmodding%2Fgameface-devtools-mcp?label=npm)](https://www.npmjs.com/package/@csmodding/gameface-devtools-mcp)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

[Plugins](#plugins) · [Install](#install) · [Development](#development)

</div>

---

## Plugins

| Plugin | Give your agent… | Runs on | Docs |
| --- | --- | --- | --- |
| 🔬 **[unity-devtools](plugins/unity-devtools/README.md)** | A live line into a **Unity Mono dev build** over the Mono Soft Debugger: see the rendered frame, reflect types, evaluate C# expressions, read & write ECS state. No code injection. Plus a driving skill. | .NET 10 SDK (Windows, Linux) | [README](plugins/unity-devtools/README.md) · [Tools reference](plugins/unity-devtools/README.md#tools) · [NuGet](https://www.nuget.org/packages/UnityDevtools.Mcp) |
| 🖼️ **[coherent-gameface](plugins/coherent-gameface/README.md)** | Eyes and hands in any **Coherent Gameface** (Cohtml) game UI over CDP: evaluate JS, screenshot, drive the DOM, console, JS breakpoints. Plus an engine skill and a driving skill. | Node 22.4+ | [README](plugins/coherent-gameface/README.md) · [Why](plugins/coherent-gameface/WHY.md) · [Tools reference](plugins/coherent-gameface/mcp/README.md) · [npm](https://www.npmjs.com/package/@csmodding/gameface-devtools-mcp) |
| 📚 **[cs2-modding](plugins/cs2-modding/README.md)** | Write **Cities: Skylines II** mods: a working loop that checks the result in the running game, and the traps an agent with the decompiled game open still falls into. Plus the `cs2-dev` MCP server, which restarts the game, waits on it, reports its errors, and runs a mod's in-game scenarios. | Node 22.4+ | [README](plugins/cs2-modding/README.md) · [Tools reference](plugins/cs2-modding/README.md#the-server) |

The two toolkit plugins are **generic**: they target any game or application embedding the
technology, with Cities: Skylines II as the reference target where everything is field-verified.
`cs2-modding` is the deliberate exception, and is about that game throughout.

> [!IMPORTANT]
> **Coherent Labs published their own Gameface MCP — which should you use?** Theirs is built around
> a `Player.exe` from a licensed Gameface SDK; this one attaches to a game that is already running.
> [**Read the full comparison →**](plugins/coherent-gameface/WHY.md)

> [!TIP]
> **Not using Claude Code or Codex CLI?** The Gameface MCP server is also published on npm as
> [`@csmodding/gameface-devtools-mcp`](https://www.npmjs.com/package/@csmodding/gameface-devtools-mcp)
> and works with any MCP client (Cursor, Gemini CLI, VS Code, …).

## Install

Add the marketplace once, then install the plugin(s) you want. Each plugin that carries an MCP
server autoloads it, version-locked to the plugin, with no setup step of your own. How it gets
there differs: `coherent-gameface` and `cs2-modding` run a bundle committed alongside the plugin,
so they need nothing but Node and work offline. `unity-devtools` needs the .NET 10 SDK and fetches
its server from NuGet the first time it launches, then caches it.

### Claude Code

Quickest setup:
```
/plugin marketplace add CitiesSkylinesModding/agents-plugins
/plugin install coherent-gameface@csmodding
/plugin install unity-devtools@csmodding
/plugin install cs2-modding@csmodding
```

Or from your terminal, `claude plugin marketplace add …` / `claude plugin install …` with the same
arguments.

> [!IMPORTANT]
> Third-party marketplaces are always left on manual updates by default. We recommend turning on
> auto updates: run `/plugin`, open the **Marketplaces** tab, select `csmodding`, then **Enable
> auto-update**.

> [!TIP]
> **Recommended setup:** \
> To install the plugin for a single project, run the terminal commands from its folder with `--scope project`:
> ```sh
> claude plugin marketplace add CitiesSkylinesModding/agents-plugins --scope project
> claude plugin install cs2-modding@csmodding --scope project
> ```
> This writes `.claude/settings.json`, which you can commit. Collaborators still need to run the
> install command once per clone.
> - Add `"autoUpdate": true` next to `source` in its `csmodding` entry to turn on auto-update for
> everyone.
> - Use `--scope local` instead to write `.claude/settings.local.json`, out of git.

> [!WARNING]
> Claude Code has a bug on some marketplaces where it sometimes won't load some plugins when you
> start a session. \
> Check that by verifying the three `/mcp`s are loaded at session start. If they're not, a simple
> `/reload-plugins` is enough.

### Codex CLI

Quickest setup:
```sh
codex plugin marketplace add CitiesSkylinesModding/agents-plugins
codex plugin add coherent-gameface@csmodding
codex plugin add unity-devtools@csmodding
codex plugin add cs2-modding@csmodding
```

> [!TIP]
> **Recommended setup:** \
> `codex plugin add` has no project scope. To install for a single project, declare the marketplace
and plugins in the project's `.codex/config.toml` instead:
> ```toml
> [marketplaces.csmodding]
> source_type = "git"
> source = "https://github.com/CitiesSkylinesModding/agents-plugins.git"
>
> [plugins."cs2-modding@csmodding"]
> enabled = true
> ```
> Then run `/mcp` to confirm the servers connected.

## Development

Uses `mise` + `bun` (never `npx`). The repository is a marketplace: plugin sources live under
`plugins/<name>/`, and everything a plugin ships lives inside its directory. The root is a bun
workspace carrying the lint/format tooling (oxlint, oxfmt) and the lefthook git hooks; the
Gameface and `cs2-dev` MCP servers are the `plugins/coherent-gameface/mcp/` and
`plugins/cs2-modding/mcp/` workspace packages, and the Unity MCP server is a .NET solution
(`agents-plugins.slnx`).

```sh
bun install         # install all workspace deps (also installs the git hooks)
mise check          # verify (read-only): type-check, lint, format
mise fix            # auto-fix lint + format in place
mise build          # rebuild every shipped artifact (commit the results)
```

The unity-devtools integration tests need Mono and skip without it; on Linux, install `mono-devel`
(`mono-runtime` alone lacks the facade assemblies they load).

Run `mise tasks` for the full list, and see [`AGENTS.md`](AGENTS.md) (plus each plugin's own
`AGENTS.md`) for the architecture notes.