# 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.

![Agent Cardroom playing-card front](assets/chatgpt-playing-card-front-v3-clean-ivory.png)
![Agent Cardroom playing-card back](assets/chatgpt-playing-card-back-v2-clean-ivory.png)

## Local installation

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

```bash
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:

```bash
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.

```bash
.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:

```text
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:

```text
Call in my Hold'em game.
```

Or start Zha Jin Hua:

```text
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](docs/plugin-submission.md).
The source website, support tracker, privacy policy, and terms are hosted in
this repository: [website](https://github.com/GZ-L/agent-cardroom),
[support](https://github.com/GZ-L/agent-cardroom/issues),
[privacy](docs/privacy.md), and [terms](docs/terms.md).

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](docs/privacy.md), [Terms](docs/terms.md), and [MIT License](LICENSE).