{"id":51575018,"url":"https://github.com/tjhavranek/mad-research","last_synced_at":"2026-07-10T23:30:55.620Z","repository":{"id":359945359,"uuid":"1248112144","full_name":"tjhavranek/mad-research","owner":"tjhavranek","description":"Three Claude Code skills for working with Codex CLI: codex-bridge (one-shot Codex calls), mad-build (Claude+Codex collaboration with cross-review), and mad-research (three-stream adversarial audit of papers, grants, reports with anonymized cross-critique and fresh-Codex synthesis).","archived":false,"fork":false,"pushed_at":"2026-05-31T15:09:33.000Z","size":1885,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T16:22:40.775Z","etag":null,"topics":["adversarial-evaluation","ai-tools","claude","claude-code","codex","multi-agent-debate","peer-review","research-audit"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tjhavranek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T07:44:58.000Z","updated_at":"2026-05-31T15:09:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tjhavranek/mad-research","commit_stats":null,"previous_names":["tjhavranek/mad-research"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/tjhavranek/mad-research","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjhavranek%2Fmad-research","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjhavranek%2Fmad-research/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjhavranek%2Fmad-research/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjhavranek%2Fmad-research/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tjhavranek","download_url":"https://codeload.github.com/tjhavranek/mad-research/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tjhavranek%2Fmad-research/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35346644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adversarial-evaluation","ai-tools","claude","claude-code","codex","multi-agent-debate","peer-review","research-audit"],"created_at":"2026-07-10T23:30:54.985Z","updated_at":"2026-07-10T23:30:55.604Z","avatar_url":"https://github.com/tjhavranek.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# mad-research: three Claude Code skills for working with Codex\n\n[![DOI](https://zenodo.org/badge/1248112144.svg)](https://doi.org/10.5281/zenodo.20829175)\n\n**For researchers who want a structured second opinion on a paper, proposal,\nor report — without writing code.**\n\nMost [Claude Code](https://claude.com/claude-code) users who also use\nChatGPT keep [Codex CLI](https://github.com/openai/codex) running in a\nseparate terminal and shuttle outputs by hand. These skills let Claude call\nCodex directly from one session — for one-shot tasks, structured\ncollaboration, or an adversarial audit — with no MCP server, no external\norchestrator, no code to write.\n\nThree independent skills in one repo. Install only the ones you want.\n\n| Skill | What it does | Use when... |\n|---|---|---|\n| **`codex-bridge`** | One-shot Codex call from inside Claude. No protocol. | You want Codex's view on a specific question without scaffolding. |\n| **`mad-build`** | Four-step Claude+Codex collaboration: independent drafts → cross-review → revisions → merge. | You're producing something (code, draft, plan) and want a structured second pair of eyes. |\n| **`mad-research`** | Three-role-stream adversarial audit of a document. Quote+page grounded criticism, anonymized cross-critique, fresh-context Codex synthesis against a locked rubric, minority report preserved. Optional opt-in **Bayesian Mode** (experimental — no documented end-to-end run yet) for evaluating the truth of a contested empirical claim. | You want a structured stress-test of a paper, grant, or referee report. See [worked example](examples/mad-research-waive/). |\n\nThese skills are the third, automated generation of the [Research Audit\nDuel + MAD protocols](https://github.com/tjhavranek/research-audit-duel-protocol)\nfamily (the manual protocols are versioned separately as Duel v1.7 / MAD\nv2.0 — see Citation below), implemented for the Claude Code + Codex CLI\ncombination.\n\n**Looking for a deeper, Claude-only workshop?** The authors' successor\nskill, [`paper-workshop` (CRUCIBLE)](https://github.com/tjhavranek/paper-workshop),\ngrew out of this project: it convenes a topic-adapted fleet of rival-tradition\nreferee seats (roundtable to summit scale), independently re-verifies every\ncomment from multiple angles, and can optionally *rebuild* the paper —\ntracked changes, re-run analyses, replication package. It is Claude-only by\ndesign, a choice informed by the comparative example below. Use\n`mad-research` when you want a fast, lightweight **cross-model** audit with\na second provider in the loop; use `paper-workshop` when you want the\ndeepest single-provider workshop and, optionally, the rebuild.\n\n## Privacy and limitations (read first)\n\n**Your documents go to two AI providers.** Both Claude and Codex send the\ntext of your manuscript and the prompts to their respective cloud APIs\n(Anthropic and OpenAI). Read each provider's data-handling policy before\nsending anything confidential, embargoed, under double-blind review, or\ncovered by an NDA. If in doubt, don't. (The opt-in **Claude-only mode**\nsends only to Anthropic — a single-provider option; see \"How to invoke\".)\n\n**The default cross-model mode needs both providers; Claude-only mode\nneeds only Claude.** The default drives two AI services: your existing\nClaude Code (Anthropic) plan, and an OpenAI Codex account — a ChatGPT\nsubscription *or* an OpenAI API key. A typical `mad-research` run is 5–6\nCodex calls over 30–60 minutes; as of June 2026 that costs roughly\n$0.10–$1.00 when Codex is billed through the OpenAI API (an estimate from\nthe authors' own metered runs on 30–50-page manuscripts, shown to you by\nthe mandatory cost gate before each run), or is covered within quota on a\nChatGPT/Codex subscription. Claude Code usage counts against your existing\nClaude plan. If you don't already hold both, expect to set up the second\none before the default mode will run end-to-end — or use the opt-in\n**Claude-only mode**, which runs on Claude alone and needs no Codex\naccount or OpenAI login at all.\n\n**Two warnings worth reading before your first run** (full list in\n[`mad-research/helpers/safety_notes.md`](mad-research/helpers/safety_notes.md)):\na quote-grounded criticism can still **overstate its severity** — acting on\nan inflated \"High\" can cost you more time than missing a minor true issue,\nso treat each surviving criticism as a candidate to weigh, not a verdict to\nobey; and manuscripts you hold **as a referee are confidential regardless\nof blinding regime** — many venues prohibit uploading submissions to cloud\nAI services outright, so check your venue's policy before running this on\na paper you are reviewing.\n\n**Multi-agent debate is not ground truth.** Smit et al. (ICML 2024) found\nthat MAD does not reliably beat a single strong model with\nself-consistency, and the 2026 literature sharpens the picture in both\ndirections: controlled studies find that *reasoning strength and group\ndiversity are the dominant drivers* of debate success while structural\ntweaks matter less, that majority pressure suppresses independent\ncorrection, and that long debates degrade through \"problem drift\"\n(arXiv:2511.07784; arXiv:2502.19559). The diversity finding cuts *in\nfavor* of this skill's cross-model premise; none of it makes any debate\noutput ground truth. Treat the audit trail this skill produces as a\nstructured critique that surfaces issues for you to evaluate — not as an\nauthoritative verdict. The \"Points rejected\" and \"Trajectory ledger\"\nsections in the final memo exist so you can audit what the protocol kept\nand what it dropped.\n\n**A first comparative look (illustrative).** We ran a comparison on five\nrecent meta-analyses: the full protocol *with* Codex (T) versus the *same*\nprotocol run *Claude-only* (C1; all streams plus a fresh-context Claude\nsubagent as synthesizer) versus the earlier 5-lens Claude panel, with a\nthird model (Gemini) judging the three memos blind on each paper — see\n[`examples/claude-only-vs-mad-3way/`](examples/claude-only-vs-mad-3way/).\nThe judge ranked `C1 \u003e T \u003e Panel` on all five papers. Stated precisely:\n**one LLM judge consistently perceived the Claude-only memos as most\nuseful** — which is evidence about perceived audit quality, not verified\ncorrectness. The example's own caveats bound it tightly: a single judge and\none run per arm mean the 5/5 unanimity measures *judge consistency*, not\nfive independent confirmations; blinding was imperfect (the Codex-arm memos\nkept protocol scaffolding the judge explicitly penalized, so part of the\ngap is presentation, not reasoning); there is no seeded ground truth; and\nthe 2026 judge-bias literature has since quantified how strong LLM-judge\nstyle and verbosity preferences are (style bias 0.76–0.92 across judge\nmodels; verbosity ≈ +17% — arXiv:2604.23178), which fits the observed\npattern: on one paper the Codex arm ranked *lower* for declining to assert\na claim it could not ground in the text — the stricter call by this skill's\nown rules. The same caveats apply, more weakly, to the protocol-beats-Panel\nmargin (the Panel summaries were also stylistically distinct, and shorter).\nThe full, single authoritative account of the example's evidence\nlimitations — including the loss of its raw per-stream files — is in the\nexample README's \"Evidence status\" section.\n\n**Why the cross-model default remains, for now.** The honest answer is that\nthe evidence is split and weak in both directions. Against: the blinded\nexample above (one judge, n = 5, confounded). For: 2026 controlled studies\nfind *group diversity* among the dominant drivers of debate success\n(arXiv:2511.07784), which is exactly what a second provider buys; and this\nrepo's own development history contains cross-model catches that a single\nfamily missed (a third-family reviewer caught a real v1.0.1 bug; a Codex\nstream rejected a fabricated reference in v0.5; v1.1.2's dual audit found\ncomplementary, non-overlapping issue sets — recorded in the CHANGELOG).\nNeither side has powered evidence. The default therefore stays cross-model\nas the design bet the diversity literature supports, the Claude-only mode\nis a first-class opt-in, and the decision will be revisited when the\nevaluation below exists. If you weigh the example more heavily than the\ndiversity literature, use Claude-only mode — that is why it ships.\n\n**Status (v1.2).** The protocol and tooling are complete for the documented\nscope and stable in use; the integrity rails (anti-tamper rule, quote\nverification, honest-degradation labels) are documented procedures followed\nby the orchestrating model, with deterministic anchors where noted (input\nand raw-memo hashes in `meta.json`) — not externally enforced code gates.\n**Bayesian Mode is experimental**: no end-to-end Bayesian-Mode run is\ndocumented yet. No configuration of this skill has been validated against\nground truth (seeded flaws or human adjudication of its memos); the planned\nevaluation is now public in [`docs/EVALUATION.md`](docs/EVALUATION.md).\nv1.2 means honestly bounded and openly specified — not proven superior.\n\n## Independent user feedback\n\n\u003e \"I wholeheartedly recommend this new AI tool from Tomas and Zuzana.\n\u003e For those who are not used to working with the terminal versions of\n\u003e Claude Code and Codex — like me — the setup required some help from\n\u003e ChatGPT. However, well worth it. I used the mad-research skill. The\n\u003e comments I received were good and caused me to make some changes to\n\u003e my paper. I also compared it to two proprietary AI review sites […].\n\u003e mad-research was comparable, if not superior. And, of course, it is\n\u003e free. mad-research will be part of standard toolkit in the future\n\u003e when writing papers.\"\n\u003e\n\u003e — **Bob Reed**, University of Canterbury — from his comment on the\n\u003e [MAER-Net announcement](https://www.maer-net.org/post/stress-testing-research-with-ai-now-super-easy-and-fully-automated),\n\u003e quoted with permission.\n\n\u003csub\u003eThe `[…]` omits two competitor sign-up links from the original comment; nothing else is altered. Note on \"free\": the skills are MIT-licensed and free; running the default cross-model mode consumes Codex/Claude usage as described in the cost note above.\u003c/sub\u003e\n\n## Install\n\n### Prerequisites\n\n1. **Claude Code.** Assumed already installed (this is a Claude Code\n   skill).\n2. **Git.** Used by the install commands below. macOS comes with Git\n   via Xcode Command Line Tools (`xcode-select --install`); Linux\n   ships it via your package manager; on Windows, install [Git for\n   Windows](https://git-scm.com/download/win) with default options.\n3. **Node.js 18+.** Download from \u003chttps://nodejs.org\u003e and run the\n   installer with default options.\n4. **Codex CLI.** Install with npm, then authenticate once via browser:\n   ```sh\n   npm install -g @openai/codex\n   codex                  # opens browser for OpenAI login\n   ```\n   Codex can authenticate via your ChatGPT account or an OpenAI API key.\n   Availability, rate limits, **and data-handling defaults** depend on which\n   path you use. The `$0.10–$1.00` per-run estimate refers to OpenAI API\n   billing. For confidential research, review the data-handling policy of\n   the path you chose (a free-tier ChatGPT login may retain prompts for\n   training); if your institution requires a specific zero-retention\n   agreement, configure Codex with an OpenAI API key under that agreement.\n\nVerify in a fresh terminal:\n```sh\ngit --version     # expect any modern version\nnode --version    # expect v18.x or higher\ncodex --version   # tested against 0.13.x; newer versions (e.g. 0.133.x) may\n                  # behave differently under --sandbox workspace-write —\n                  # see helpers/invoke_codex.md and run the doctor\n```\n\nIf you cannot install Git, you can also use GitHub's \"Download ZIP\"\nbutton (green Code button on the repo page) and unpack the archive\nto your temp directory. Replace `git clone ...` in the commands\nbelow with the unpack step. **Note:** GitHub ZIPs unpack into a\nbranch-named folder (typically `mad-research-main/`), so replace\n`/tmp/mad-research` (macOS/Linux) or `$env:TEMP\\mad-research`\n(Windows) in the commands below with the actual unpacked path. **If you\ninstalled via ZIP, also skip the `rm -rf` / `Remove-Item` line that deletes the\ntemp checkout and point only the copy step at your unpacked folder** — otherwise\nthat line can remove the very folder you just unpacked.\n\nThe install commands below are safe to re-run: they refresh the temp\ncheckout, and they replace an installed skill **only after verifying the\nfreshly cloned copy exists** — so a failed download (network hiccup,\nGitHub outage) leaves your existing install untouched instead of deleting\nit.\n\n### Quick start: install all three skills\n\n#### macOS / Linux\n\n```sh\nmkdir -p ~/.claude/skills\nrm -rf /tmp/mad-research\ngit clone https://github.com/tjhavranek/mad-research /tmp/mad-research\nfor skill in codex-bridge mad-build mad-research; do\n  if [ -d /tmp/mad-research/$skill ]; then\n    rm -rf ~/.claude/skills/$skill\n    cp -r /tmp/mad-research/$skill ~/.claude/skills/$skill\n  else\n    echo \"SKIPPED $skill: clone incomplete — existing install left untouched\"\n  fi\ndone\n```\n\n#### Windows (PowerShell)\n\n```powershell\n$skillsDir = \"$env:USERPROFILE\\.claude\\skills\"\n$tempRepo  = \"$env:TEMP\\mad-research\"\nNew-Item -ItemType Directory -Force $skillsDir | Out-Null\nif (Test-Path $tempRepo) { Remove-Item -Recurse -Force $tempRepo }\ngit clone https://github.com/tjhavranek/mad-research $tempRepo\nforeach ($skill in 'codex-bridge','mad-build','mad-research') {\n  $src  = Join-Path $tempRepo $skill\n  $dest = Join-Path $skillsDir $skill\n  if (Test-Path $src) {\n    if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }\n    Copy-Item -Recurse $src $dest\n  } else {\n    Write-Host \"SKIPPED ${skill}: clone incomplete - existing install left untouched\"\n  }\n}\n```\n\n### Install one skill only\n\nEach skill is self-contained. Replace `\u003cskill-name\u003e` with the one you\nwant (`codex-bridge`, `mad-build`, or `mad-research`).\n\n#### macOS / Linux\n\n```sh\nSKILL=mad-research                              # or codex-bridge / mad-build\nmkdir -p ~/.claude/skills\nrm -rf /tmp/mad-research\ngit clone https://github.com/tjhavranek/mad-research /tmp/mad-research\nif [ -d /tmp/mad-research/$SKILL ]; then\n  rm -rf ~/.claude/skills/$SKILL\n  cp -r /tmp/mad-research/$SKILL ~/.claude/skills/$SKILL\nelse\n  echo \"SKIPPED: clone incomplete — existing install left untouched\"\nfi\n```\n\n#### Windows (PowerShell)\n\n```powershell\n$skill     = \"mad-research\"                     # or codex-bridge / mad-build\n$skillsDir = \"$env:USERPROFILE\\.claude\\skills\"\n$tempRepo  = \"$env:TEMP\\mad-research\"\nNew-Item -ItemType Directory -Force $skillsDir | Out-Null\nif (Test-Path $tempRepo) { Remove-Item -Recurse -Force $tempRepo }\ngit clone https://github.com/tjhavranek/mad-research $tempRepo\n$src  = Join-Path $tempRepo $skill\n$dest = Join-Path $skillsDir $skill\nif (Test-Path $src) {\n  if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }\n  Copy-Item -Recurse $src $dest\n} else {\n  Write-Host \"SKIPPED: clone incomplete - existing install left untouched\"\n}\n```\n\n### Update an existing install\n\nRe-run whichever Quick-start block above matches your platform. The\ncommands replace each installed skill with the freshly cloned copy (and\nleave it untouched if the clone failed), so they also work as updates.\n\n### Verify the install\n\n**Restart Claude Code** (skills are loaded at session start). Then ask\nClaude in natural language for the doctor of whichever skill you installed:\n\n```\nRun the mad-research doctor.\nRun the mad-build doctor.\nRun the codex-bridge doctor.\n```\n\nEach skill ships its own `helpers/doctor.md`, so users who installed only one\nskill should ask for that skill's doctor — not `mad-research`'s. The doctor\nprints whether Node, npm, Codex, the expected `codex exec` flags, and Codex\nauthentication all check out. If any check fails it tells you exactly what to\ninstall or fix.\n\n## How to invoke\n\n| You say | Skill that fires |\n|---|---|\n| \"have Codex draft X\" / \"ask Codex to review file Y\" / \"run Codex on this\" | `codex-bridge` |\n| \"MAD-build a script that does X\" / \"have Codex help me build Y\" / \"competition agent on this\" | `mad-build` |\n| \"MAD-research this paper\" / \"stress-test this proposal\" / \"referee report on attached.pdf\" | `mad-research` |\n\nYou can also just say `Run MAD on file.pdf`; Claude routes to the\nright skill based on the file type and the verbs you used.\n\nTo run `mad-research` **Claude-only** — single-provider, with all streams\nand the synthesis done by fresh-context Claude subagents instead of Codex —\nadd *\"Claude-only\"* to the request (e.g. *\"MAD-research this paper,\nClaude-only\"*). The default remains the Codex cross-model run; the\nClaude-only configuration is an explicit, labelled opt-in (motivated by the\n[3-way comparison](examples/claude-only-vs-mad-3way/)), distinct from the\ndegraded in-session fallback used when Codex is simply unavailable.\n\n## See also\n\n- A real `mad-research` audit, end-to-end: [`examples/mad-research-waive/`](examples/mad-research-waive/).\n- Does Codex add value? A blinded 3-way comparison on five meta-analyses: [`examples/claude-only-vs-mad-3way/`](examples/claude-only-vs-mad-3way/).\n- The deep Claude-only successor workshop (review + rebuild):\n  [`paper-workshop` (CRUCIBLE)](https://github.com/tjhavranek/paper-workshop) —\n  see \"Looking for a deeper, Claude-only workshop?\" above for how the two relate.\n- The planned ground-truth evaluation of this skill: [docs/EVALUATION.md](docs/EVALUATION.md).\n- The manual two-model / four-model protocols this builds on:\n  \u003chttps://github.com/tjhavranek/research-audit-duel-protocol\u003e.\n- Changelog and version history: [CHANGELOG.md](CHANGELOG.md).\n\n## License\n\nMIT. Use, modify, share. Credit the authors.\n\n## Citation\n\nHavránek, T., \u0026 Iršová, Z. (2026). *mad-research: Claude Code skills for\nadversarial multi-agent debate on research documents*. Zenodo.\n\u003chttps://doi.org/10.5281/zenodo.20829175\u003e\n\nFor the underlying methodology (Duel v1.7 / MAD v2.0) please also cite:\nIršová \u0026 Havránek (2026), *Research Audit Protocols: Duel + MAD*,\nZenodo, \u003chttps://doi.org/10.5281/zenodo.19105954\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftjhavranek%2Fmad-research","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftjhavranek%2Fmad-research","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftjhavranek%2Fmad-research/lists"}