codex-choice-cards

Clickable choice cards for Codex and ChatGPT — decisions, multi-select, and self-checking quizzes, all in one lightweight MCP plugin.

---

What it does

When an AI agent needs to ask a question with discrete options, codex-choice-cards renders a native clickable card inside the conversation. The user taps a choice; the selection is automatically sent back to the agent as a message — no typing required.

Three modes are supported:

Mode	Behaviour
single	Tap one option → immediately submitted
multi	Tick several options → submit with a button
quiz	Tap one → instant right/wrong feedback with explanation

When the native card UI is unavailable (e.g. API-only clients), the bundled Codex skill prints a numbered text list as fallback — the user can reply with a number and the agent continues normally.

---

Installation

Via Codex Plugins browser (recommended)

1. Open Codex → Plugins → Browse.
2. Search for Choice Cards and click Install.
3. The included .mcp.json starts the local Node.js server automatically.

Manual / self-hosted

git clone https://github.com/yueeeee8588/codex-choice-cards.git
cd codex-choice-cards
npm ci
node server.mjs   # starts on stdio by default

Then point your MCP client at the running server.

---

Usage

Call the show_choice_cards tool from inside Codex or any MCP-compatible agent:

// single-choice example
{
  "question": "Which study block should we tackle first?",
  "options": [
    { "label": "A. Anatomy flashcards",      "description": "Origin & insertion review" },
    { "label": "B. Rehab evaluation MCQs",   "description": "Gait analysis + balance" },
    { "label": "C. English vocabulary drill" }
  ],
  "mode": "single",
  "title": "Tonight's plan"
}

// quiz example (self-checking)
{
  "question": "Which Brunnstrom stage first shows synergistic movement?",
  "options": [
    { "label": "A. Stage I",   "description": "Flaccid, no voluntary movement" },
    { "label": "B. Stage II",  "description": "Associated reactions, synergy begins" },
    { "label": "C. Stage III", "description": "Synergy peaks, spasticity maximal" }
  ],
  "mode": "quiz",
  "answerIndex": 1,
  "explanation": "Stage II marks the onset of associated reactions and synergistic patterns; full synergy peaks in Stage III."
}

Tool schema

Parameter	Type	Required	Description
question	string	✅	The question shown at the top of the card
options	array	✅	List of { label, description? } objects (2–8 items)
mode	string	✅	"single" | "multi" | "quiz"
title	string		Optional card title / header
answerIndex	number	quiz only	Zero-based index of the correct answer
explanation	string		Explanation shown after the user picks (quiz mode)

---

Repository layout

codex-choice-cards/
├── server.mjs                  # MCP server — exposes show_choice_cards tool
├── public/
│   └── choice-cards.html       # In-conversation card UI (rendered by Codex)
├── skills/
│   └── choice-cards/
│       └── SKILL.md            # Agent skill: mode selection guidance + fallback logic
├── examples/
│   ├── single.json             # Example single-choice payload
│   ├── multi.json              # Example multi-select payload
│   └── quiz.json               # Example quiz payload
├── scripts/
│   └── create-choice-cards.mjs # Helper for local dev / smoke tests
├── smoke-test.mjs              # End-to-end smoke test
├── .codex-plugin/
│   └── plugin.json             # Codex plugin manifest
└── .mcp.json                   # MCP server launch config

---

Development

npm ci             # install deps
npm run check      # syntax check (node --check)
node smoke-test.mjs  # end-to-end smoke test — should print PASS for all modes

Pull requests and issues are welcome. See CONTRIBUTING.md for guidelines.

---

Why this exists

Codex is great at reasoning, but its raw text confirmations ("enter 1, 2, or 3") create friction. This plugin replaces that pattern with a first-class interactive card — tappable on desktop and mobile — while keeping a numbered fallback for headless / API contexts. The result is smoother multi-step agent workflows with less back-and-forth.

---

License

MIT © yueeeee8588