Agent Cardroom

Agent Cardroom is a local Codex plugin for virtual-chip poker against 1–5 built-in bot opponents. It supports Texas Hold'em and Zha Jin Hua. It has no accounts, real-money play, or persistent game history.

Local installation

Clone the source checkout, then install the package for the current user with the same python3 executable that the plugin mapping invokes:

git clone https://github.com/GZ-L/agent-cardroom.git
cd agent-cardroom
python3 -m pip install --user .
python3 -m agent_cardroom.mcp_stdio --help

The module check is intentionally after installation. Install the plugin from this checkout in Codex using the repo-local marketplace manifest at .agents/plugins/marketplace.json, or install the bundle at plugins/agent-cardroom/. Both mappings run python3 -m agent_cardroom.mcp_stdio, so they do not depend on a virtual environment directory being on Codex's PATH.

For development and the full test suite, create an isolated environment:

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

Verification and local adapters

The following commands use this checkout's installed virtual environment. Run the HTTP command only when you want to serve the local adapter; it continues running until interrupted.

.venv/bin/python -m pytest tests/test_acceptance.py -v
.venv/bin/python -m pytest -v
.venv/bin/ruff check src tests
git diff --check
.venv/bin/agent-cardroom-http --host 127.0.0.1 --port 8000

These are the project's portable checks. Codex/plugin-directory manifest validation is performed in a Codex environment during the owner-operated publication process; it is not a GitHub-agnostic checkout command.

For a hosted adapter, sessions expire after 60 idle minutes. To remove local state, stop the adapter and start it again; games are not saved permanently.

Playing

Ask the plugin to start a game, for example:

Start a Texas Hold'em game with 3 bot opponents and 1,000 virtual chips.

In an Agent that supports MCP Apps UI, the plugin follows this opening call by showing an interactive table in the current conversation. Click the legal actions and the 25% / 33% / 75% / 133% / double quick-bet options directly; the table displays only virtual Token balances, the current pot, table stakes, and server-approved cards. It does not use a real wallet, deposits, or withdrawals.

If the UI is unavailable, act from the returned state in text:

Call in my Hold'em game.

Or start Zha Jin Hua:

Start a Zha Jin Hua game with 2 bot opponents and 500 virtual chips.

This project is for entertainment with virtual chips and virtual Tokens only. Do not use it for real-money gambling.

Public submission

Public-directory publication is a manual, identity-bound, owner-operated process, separate from local installation. The authorized owner must create and push a public repository, host a stable HTTPS MCP endpoint, complete domain verification, and submit via the Codex directory portal. Tests do not upload code, create GitHub repositories, alter DNS, or submit to the OpenAI portal. The local .mcp.json mapping is only for GitHub-download installation; it is not accepted as the public submission artifact. See the submission checklist. The source website, support tracker, privacy policy, and terms are hosted in this repository: website, support, privacy, and terms.

For a public deployment, set MCP_ALLOWED_HOSTS to a comma-separated list of your deployment hostnames. The Render service at agent-cardroom.onrender.com is included as the initial deployment hostname; add a custom domain before switching the public listing to it.

See Privacy, Terms, and MIT License.