# Game Harness agent guide

The official Game Harness plugin is the recommended connection; install it through the client's supported flow. Without the plugin, this same account connection can be registered once with `game-harness connect mcp`; use the plugin or that registration, not both. A kit that is already installed needs neither: local game work uses the installed CLI directly. Do not create a per-project plugin.

The `game-harness connect mcp` commands require an installed CLI. If no CLI is installed, use the official plugin or the manual kit instructions below first. Account-assisted installation uses its verified private executable and does not change PATH.

This guide is not evidence that the plugin has been published in a client's directory. Use verified installation metadata; do not invent an installation link or claim an unavailable integration is connected.

## Official plugin installation

The official channel is Game-Harness/game-harness-plugin. The package is not listed in clients' public plugin directories. Codex gets the onboarding skill and account MCP; feedback hooks are Claude Code only.

While the channel is private, installation requires Git, invited read access to the plugin channel repository, and a Git credential helper that can authenticate without prompting. Engine source access is not required. Client sign-in and Game Harness account consent are separate from Git access. Working SSH access alone does not establish Codex HTTPS access; use the pinned kit fallback if channel access is unavailable. Never put a token in the URL or command line.

Claude Code 2.1.292 or later:

    claude plugin install game-harness --marketplace Game-Harness/game-harness-plugin --scope user

Codex:

    codex plugin marketplace add Game-Harness/game-harness-plugin
    codex plugin add game-harness@game-harness --json

### Update the channel installation

In Claude Code, refresh the marketplace before updating the plugin, then restart when prompted:

    claude plugin marketplace update game-harness
    claude plugin update game-harness@game-harness

In Codex:

    codex plugin marketplace upgrade game-harness

The same channel commands apply after the repository becomes public; Git remains required, but public repository reads need no GitHub account or stored Git credential. Channel installation does not establish a public directory listing.

### Pinned kit fallback

Use the plugin archive from the same kit as your CLI and verify the kit's SHA256SUMS before extraction. The filename `game-harness-plugin-<kit-version>.tgz` uses the actual kit version, which is separate from the plugin manifest version. From a kit directory containing exactly one matching plugin archive:

    mkdir -p game-harness-plugin
    tar -xzf game-harness-plugin-*.tgz -C game-harness-plugin

Claude Code:

    claude plugin install game-harness --marketplace "$(pwd)/game-harness-plugin/package" --scope user --json

Codex:

    codex plugin marketplace add "$(pwd)/game-harness-plugin/package" --json
    codex plugin add game-harness@game-harness --json

Keep the extracted directory in place. This is the kit's pinned copy, not an automatic channel subscription. Local plugin installation needs no GitHub account or stored Git credential; using account services still requires normal account sign-in and consent.

### Conversation activation and account consent

Start a new conversation after installation. In an existing Claude conversation, enter `/reload-plugins` and confirm success before attaching. Installed or enabled inventory does not prove that tools and skills are active in the current conversation.

An installed kit or suitable CLI can attach locally without Game Harness account sign-in. For account services, use the one official account connection and explicitly accept any required terms. CLI downloads require approved beta access and an admitted, ready, selected CLI for the platform; non-ready results explain what is missing and install nothing. Use the plugin or `game-harness connect mcp` for the account MCP, not both.

## Install and attach

An installed Game Harness kit lets a local agent use the CLI directly against the user's game host, without an account or plugin. The optional official account MCP provides account, beta/license and verified CLI preparation services; it does not relay project traffic.

After connecting (plugin or registered account connection), call game_harness_start for the current setup instructions. Use its packaged Game Harness skill for project creation and the installed release's attachment workflow when the plugin is installed; otherwise follow the attachment result's next command.

For manual installation, follow the Downloads page and the kit's documentation archive: package/book/start/install.md and package/book/start/connect-your-agent.md. Verify SHA256SUMS, install the platform CLI on PATH as game-harness and make it executable. Run game-harness for guided setup; it installs the embedded SDK when creating a game. Existing managed games use their repository's setup command and reviewed runtime lock.

For account services, register the one official account MCP through the client's supported connection flow, or use the optional official plugin. From an installed kit, game-harness connect mcp --client codex or game-harness connect mcp --client claude prints the client command for review. Once connected, call game_harness_start for current instructions. Use the installed release's skills and attachment workflow. Do not create a per-project plugin or register a second account MCP.

If no CLI is installed, detect the local platform and call game_harness_prepare_install. It uses this existing account connection to select an approved standalone binary from the release kit. Complete any required beta access and show exact terms for explicit user agreement; never accept silently. Follow the returned download, byte-length, SHA-256 and offline version checks before execution. The CLI carries its SDK and prepares a verified private Bun runtime on first use; no separate Bun installation is needed. Run the verified binary without arguments for guided setup, or use its supported agent attachment commands. No second GitHub login or project MCP registration is required. The local agent performs installation; this tool does not run commands on a user's computer.

In an existing project directory, the current local entry commands are:

    game-harness agents attach --dir . --json
    game-harness mcp tools --dir . --json
    game-harness mcp schema <tool-name> --dir . --json
    game-harness mcp call <tool-name> --dir . --args @request.json --json

If you use account services, keep one official account MCP installed. Local CLI requests go directly to the user's host. After attachment, follow its returned toolsCommand and nextCommand to preserve agent identity. For a private CLI install, use the verified absolute binary in place of the leading game-harness executable and preserve every other argument; PATH was not changed. Inspect hostRunner.canDispatch before relying on a local authenticated runner. Registration alone does not make the current conversation resumable.

Use ordinary project file edits for code. Use the CLI for host operations, assets, module tools, diagnostics and preview acceptance; discover schemas from the host.

## Keep the user in the iteration

Read the host's game-tasks playbook and discover its current operation schemas before authoring. Select the authorized project, inspect its health and follow the returned preview instructions.

Use the preview target and next action reported by `project.health`. Browser preview is the default for first use. Native preview is an explicit opt-in and requires a matching native-player artifact for the installed SDK, operating system and architecture. Opening Studio alone does not prove that the selected game preview is playable; verify its readiness and input separately.

Keep the managed preview session through edits. Give the user the verified preview entry and controls, inspect diagnostics and the accepted source revision, and inspect a fresh capture of the changed result. A URL or attachment receipt does not prove a rendered frame or that the user is playing.

A supported desktop browser may expose Studio site tools through the open, authorized Studio page. Preserve that page and its project scope. Site tools are not a replacement of the official account MCP endpoint.

## Self-hosted connection

Owned-host discovery is a staging capability restricted to the existing approved beta identities. Check the signed-in game_harness_start response for this connection's eligibility; public documentation grants no access. Reuse the native connect account OAuth connection, or the canonical signed-in browser session. A running host advertises only a signed opaque instance; no project registration is required. Use peer discover and peer connect, or the browser connection page. The client creates an X25519 identity on first pairing and retains it locally for the same account and pinned host. The browser retains a nonextractable key in its own profile; the native client uses its existing encrypted connection profile. Reconnecting reuses this client identity to decrypt a fresh bounded introduction locally. Presence and introduction requests remain short-lived. Host-issued scoped access, project discovery, source, previews and tool traffic remain direct. Existing pinned host keys must match. A supported direct HTTPS host route can be included only inside the sealed response when NAT traversal is unavailable. Established direct connections do not depend on the introduction service; host grants still expire or revoke locally. The official plugin remains subject to its separate client installation/publication status. For private ChatGPT web, call game_harness_hosts through this account connection to list your own advertised instances. A current signed presence lease does not prove direct reachability, a project grant, or an installed connector. Use the selected host's separate private ChatGPT connection to check health and access an approved project.

The native Game Harness peer client can exchange one encrypted offer and answer through this anonymous five-minute introduction service. Share the fragment invitation only with the intended peer. Discovery capabilities are independent of project grants; never send account OAuth, project credentials or the invitation encryption key to the service. Project traffic stays direct. Restricted networks can prevent connection and there is no relay fallback. The service and peers can observe connection addresses. A cloud MCP client still needs a supported local executor or direct transport.

For private ChatGPT web, keep the official account connection and configure a separate private connection to the user's host. Copy the exact HTTPS MCP endpoint shown by Studio; never add credentials to the URL. Complete that host's OAuth flow and explicitly approve the intended project on the host, then select both private connections in the same conversation. Account sign-in does not grant project access. If the host list is empty or the host connection is unavailable, ask the owner to start the intended host, enable its existing authenticated HTTPS sharing, and check again. Do not infer a provider outage from an empty list. Use a client-supported direct connection to the user's own host, or a local agent using the CLI. A tool result cannot reconfigure every cloud client's MCP endpoint. Do not upload project details or host credentials here.

Account sign-in identifies the owner; only the self-hosted runtime grants project access. Check the current ownedHosts.enabled capability before using automatic discovery. Keep project inventory, source, assets, previews and project credentials on the user's host.

## Official account and setup resources

- Official account MCP: https://accounts.gameharness.dev/mcp
- Account: https://accounts.gameharness.dev/account
- Downloads: https://accounts.gameharness.dev/get
- API documentation: https://accounts.gameharness.dev/openapi.json
- Module catalogue: https://stage.gameharness.dev/api/v2/modules
- Peer introduction capabilities: https://accounts.gameharness.dev/peer/v1/info
