Skip to content
Back to search

theorist-toolbox

A toolkit of Claude Code skills for doing economic theory with LLMs: math-proof (single-pass proving), codex-math (adversarial verification), and co-math (multi-agent proof projects). With a VCG-for-grade-inflation case study.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/morankor--theorist-toolbox/badge.svg)](/listings/morankor--theorist-toolbox)

HTML

<a href="/listings/morankor--theorist-toolbox"><img src="/api/listings/morankor--theorist-toolbox/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code version

These are Claude Code skills and agents. The easiest path is the installer:

./install.sh          # the six skills -> ~/.claude/skills/
./install.sh --all    # + co-math agents and strict-mode hooks (needed for the co-math workflow)

It backs up anything it would overwrite to a timestamped folder under `~/.claude/backups/` and verifies each skill's frontmatter afterwards. `--dry-run` previews without writing; `--dest DIR` installs somewhere other than `~/.claude`; `--with-agents` / `--with-co-math` pick pieces individually.

Or copy by hand — the skills into your skills directory, and, for the `co-math` workflow, the agents and hooks alongside:

cp -R skills/* ~/.claude/skills/
cp -R agents/* ~/.claude/agents/   # only needed for the co-math project workflow
cp -R co-math ~/.claude/co-math    # strict-mode hooks + helper tools for co-math projects

Then invoke them from Claude Code (`/math-proof`, `/co-math-init`, …) or let the model pick them up by description.

OpenAI Codex version

The Codex version lives in [`codex/`](codex/). It translates the same proof discipline into Codex-native skills and custom-agent profiles:

- [`codex/.agents/skills/`](codex/.agents/skills/) — Codex skills for `math-proof`, `codex-math`, `co-math-init`, `co-math-status`, and `proof-readability`. - [`codex/.codex/agents/`](codex/.codex/agents/) — Codex custom-agent profiles for the co-math team roles.

Install it into a Codex workspace or repo:

cp -R codex/.agents /path/to/repo/
cp -R codex/.codex /path/to/repo/

Then start Codex from that repo and invoke, for example:

Use $math-proof to prove the stated result.
Use $co-math-init to initialize a strict co-math project for: <research question>

Codex only spawns subagents when explicitly asked, so the co-math role profiles are written to work both as single-agent guidance and as explicit Codex custom agents.

ChatGPT prompt pack

The ChatGPT version lives in [`chatgpt/`](chatgpt/). Use [`chatgpt/custom-gpt-instructions.md`](chatgpt/custom-gpt-instructions.md) as the instruction block for a custom GPT or project, attach [`chatgpt/knowledge/theorist-toolbox-reference.md`](chatgpt/knowledge/theorist-toolbox-reference.md) as a compact reference, or copy prompts directly from [`chatgpt/prompts/`](chatgpt/prompts/).

Notes

- **`codex-math`** documents the *interface* to a set of companion runner scripts (`codex_verify.sh`, `codex_write.sh`, `codex_explore.sh`) that wrap the [OpenAI Codex CLI](https://github.com/openai/codex). Those live alongside your project (`code/utils/codex_math/`) and call `codex exec`; you'll need the Codex CLI installed and authenticated. The skill is the playbook for using it well. - **`co-math-init`** writes per-project hooks that reference `~/.claude/co-math/hooks/` (a `paper_tex_guard.py`, a `workstream_complete_guard.py`, and a `blocked_workstreams_notice.py` that enforce strict mode). These now ship in [`co-math/`](co-math/) — copy it to `~/.claude/co-math` as shown above. Running with the guards disabled also works; the hooks are the teeth. - **`second-brain`** carries its own Python package in `skills/second-brain/package/` and installs it into a per-library virtualenv on first use (`python3 -m venv` + `pip install`); it needs Python 3.11+ and, for PDF ingestion, the optional `marker` OCR dependency. - **`lean-prover`** needs a working Lean 4 toolchain (`lean` and `lake` on `PATH`); it pins the toolchain per workstream and builds against mathlib. Without it the agent blocks the workstream cleanly rather than faking a proof. Every other agent runs with no extra tooling.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 201 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Theorist Toolbox
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  3. [![arXiv](https://img.shields.io/badge/arXiv-2606.22337-b31b1b.svg)](https://arxiv.org/abs/2606.22337)
  4. [![Claude Code](https://img.shields.io/badge/Claude%20Code-skills%20%26%20agents-da7756.svg)](https://claude.com/claude-code)
  5. [![OpenAI Codex](https://img.shields.io/badge/OpenAI%20Codex-version-10a37f.svg)](codex/)
  6. [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
  7. *Shared tooling for doing economic theory with LLMs — prove results, check them, and run a proof-building project like a research team, without letting the model hand-wave.*
  8. > **If you use this toolbox, please cite:** Moran Koren (2026), *Theorist Toolbox: Tools for Agent-Based LLM-Assisted Economic Theory Research*, arXiv:2606.22337 — <https://arxiv.org/abs/2606.22337>.
  9. <details><summary>BibTeX</summary>
  10. ```bibtex
  11. @article{koren2026theorist,
  12. title = {Theorist Toolbox: Tools for Agent-Based LLM-Assisted Economic Theory Research},
  13. author = {Koren, Moran},
  14. year = {2026},
  15. eprint = {2606.22337},
  16. archivePrefix = {arXiv},
  17. url = {https://arxiv.org/abs/2606.22337}
  18. }
  19. ```
  20. </details>
  21. A small set of Claude Code *skills* for doing economic theory with LLMs — proving
  22. results, checking them, and running a whole proof-building project the way you'd run
  23. a research team. An OpenAI **Codex version** is also included in [`codex/`](codex/),
  24. with companion ChatGPT instructions in [`chatgpt/`](chatgpt/).
  25. Empirical economists have had shared tooling for years. The empiricist learns the
  26. craft from reusable, opinionated tools. Theorists rarely really got that. This is an
  27. attempt at the theory-side equivalent: a toolkit that encodes *how* to push an LLM
  28. through a proof without letting it hand-wave.
  29. The skills are different bets on the same problem — *how do you get
  30. machine help on a theorem you don't already know how to prove, and trust the answer?*
  31. ## The skills
  32. | Skill | The bet | What it is | Status |
  33. |-------|---------|-----------|--------|
  34. | **`math-proof`** | One careful pass. | A discipline for writing a full, gap-free proof in a single shot: state what you'll show before showing it, sign every term, no "clearly," no overgeneralizing from examples. | ✅ stable · no deps |
  35. | **`codex-math`** | Two minds, one adversarial. | Drives OpenAI Codex (gpt-5.5) as a *co-processor and hostile verifier* — propose, then try to break, then triage. Built around the rule that Codex is a brilliant, unreliable mathematician: every output is a lead, not a verdict. | ⚙️ needs OpenAI Codex CLI |
  36. | **`co-math-init` / `co-math-status`** | A research team, not a chat. | Scaffolds a structured proof-building *project* — `paper.tex`, goals, decisions log, workstreams, strict mode where every gap is flagged `\unproven{}` and nothing is "complete" without a reviewer's sign-off. The architecture follows Zheng et al. (2026), *AI co-mathematician* (Google DeepMind). `co-math-status` renders the project state. | ✅ stable · agents required, hooks in [`co-math/`](co-math/) |
  37. | **`proof-readability`** | Correctness first, then clarity. | A post-verification exposition pass for proofs that are *already* verified — six layers (architecture, signposting, line-level justification, notation, intuition, grammar) that minimise the reader's work without ever changing the mathematics. In a co-math project the coordinator runs it after a proof is approved; a suspected gap routes the workstream back to the prover rather than getting quietly patched. | ✅ stable · no deps |
  38. | **`second-brain`** | Read the literature exactly. | An academic "second brain" — agentic RAG over a local library of theoretical papers. LaTeX-aware ingestion (theorems/proofs chunked with their custom macros and prerequisite definitions auto-bundled), hybrid search, and an MCP server so Claude Code can answer questions against the library directly. Ships the complete `brain` Python package with its test suite. | ⚙️ needs Python 3.11+ (installs its own venv) |
  39. Each is a different point on a trade-off between speed, verification, and coverage:
  40. the single pass is fastest and cleanest but unchecked; the adversarial pair is the
  41. most reliable per claim; the structured team gives the broadest, most disciplined
  42. coverage and can *reject its own work*; `proof-readability` runs after any of them
  43. to make an accepted proof legible.
  44. ### The co-math agents (`agents/`)
  45. The `co-math-init` project is run by a small team of Claude Code sub-agents, shipped
  46. in [`agents/`](agents/):
  47. | Agent | Role |
  48. |-------|------|
  49. | `project-coordinator` | The front door — reads `goals.md`, formalises intent, dispatches and steers workstreams. |
  50. | `literature-reviewer` | Literature searches and verified, cited workstream reports. |
  51. | `prover` | Drafts proofs into `paper.tex` with strict discipline — every step justified, cited, or `\unproven{}`. Also runs the `proof-readability` pass in readability mode. |
  52. | `coder` | Python for computational exploration and numerical verification, with mandatory tests and golden values. |
  53. | `lean-prover` | Formalises a lemma in Lean 4 and verifies it with `lake build`. A green build is the strongest "proven" the system supports — `paper-reviewer` re-runs the build rather than re-checking the mathematics, and the theorem is closed with `\leanproved{}`. |
  54. | `paper-reviewer` | Adversarial gate — a workstream cannot be marked complete until it writes an explicit approval file. |
  55. 📐 **Diagrams:** see [`docs/co-math-architecture.md`](docs/co-math-architecture.md) for the agent topology, the workstream lifecycle, and the verification ladder (informal proof → Lean-verified → readable).
  56. ## The case study (`examples/`)
  57. I built these while testing all three on one problem: turning the *eigengrade* of
  58. Gans & Kominers (2026, *"What Does a Grade Mean?"*, NBER w35183) into a VCG-style
  59. mechanism against grade inflation. Each skill produced a self-contained writeup:
  60. - `1-math-proover_…` — a student-side enrollment VCG (single pass, `math-proof`).
  61. - `2-codex-proover_…` — an instructor-side Pigouvian/Groves transfer, adversarially
  62. verified with Codex + Monte Carlo (`codex-math`).
  63. - `3-co-math_…` — a money-free, report-space mechanism *suite* with an impossibility
  64. theorem and a numerically validated running example (`co-math`).
  65. Two of the three independently rediscovered the same externality kernel; the third's
  66. reviewer gate killed one of its own sub-goals. The write-up of that comparison lives
  67. in the accompanying Substack post.
  68. ## Install
  69. ### Claude Code version
  70. These are Claude Code skills and agents. The easiest path is the installer:
  71. ```bash
  72. ./install.sh # the six skills -> ~/.claude/skills/
  73. ./install.sh --all # + co-math agents and strict-mode hooks (needed for the co-math workflow)
  74. ```
  75. It backs up anything it would overwrite to a timestamped folder under
  76. `~/.claude/backups/` and verifies each skill's frontmatter afterwards.
  77. `--dry-run` previews without writing; `--dest DIR` installs somewhere other
  78. than `~/.claude`; `--with-agents` / `--with-co-math` pick pieces individually.
  79. Or copy by hand — the skills into your skills directory, and, for the
  80. `co-math` workflow, the agents and hooks alongside:
  81. ```bash
  82. cp -R skills/* ~/.claude/skills/
  83. cp -R agents/* ~/.claude/agents/ # only needed for the co-math project workflow
  84. cp -R co-math ~/.claude/co-math # strict-mode hooks + helper tools for co-math projects
  85. ```
  86. Then invoke them from Claude Code (`/math-proof`, `/co-math-init`, …) or let the model
  87. pick them up by description.
  88. ### OpenAI Codex version
  89. The Codex version lives in [`codex/`](codex/). It translates the same proof
  90. discipline into Codex-native skills and custom-agent profiles:
  91. - [`codex/.agents/skills/`](codex/.agents/skills/) — Codex skills for
  92. `math-proof`, `codex-math`, `co-math-init`, `co-math-status`, and
  93. `proof-readability`.
  94. - [`codex/.codex/agents/`](codex/.codex/agents/) — Codex custom-agent profiles
  95. for the co-math team roles.
  96. Install it into a Codex workspace or repo:
  97. ```bash
  98. cp -R codex/.agents /path/to/repo/
  99. cp -R codex/.codex /path/to/repo/
  100. ```
  101. Then start Codex from that repo and invoke, for example:
  102. ```text
  103. Use $math-proof to prove the stated result.
  104. Use $co-math-init to initialize a strict co-math project for: <research question>
  105. ```
  106. Codex only spawns subagents when explicitly asked, so the co-math role profiles
  107. are written to work both as single-agent guidance and as explicit Codex custom
  108. agents.
  109. ### ChatGPT prompt pack
  110. The ChatGPT version lives in [`chatgpt/`](chatgpt/). Use
  111. [`chatgpt/custom-gpt-instructions.md`](chatgpt/custom-gpt-instructions.md) as the
  112. instruction block for a custom GPT or project, attach
  113. [`chatgpt/knowledge/theorist-toolbox-reference.md`](chatgpt/knowledge/theorist-toolbox-reference.md)
  114. as a compact reference, or copy prompts directly from
  115. [`chatgpt/prompts/`](chatgpt/prompts/).
  116. ### Notes
  117. - **`codex-math`** documents the *interface* to a set of companion runner scripts
  118. (`codex_verify.sh`, `codex_write.sh`, `codex_explore.sh`) that wrap the
  119. [OpenAI Codex CLI](https://github.com/openai/codex). Those live alongside your
  120. project (`code/utils/codex_math/`) and call `codex exec`; you'll need the Codex CLI
  121. installed and authenticated. The skill is the playbook for using it well.
  122. - **`co-math-init`** writes per-project hooks that reference
  123. `~/.claude/co-math/hooks/` (a `paper_tex_guard.py`, a
  124. `workstream_complete_guard.py`, and a `blocked_workstreams_notice.py` that enforce
  125. strict mode). These now ship in [`co-math/`](co-math/) — copy it to
  126. `~/.claude/co-math` as shown above. Running with the guards disabled also works;
  127. the hooks are the teeth.
  128. - **`second-brain`** carries its own Python package in
  129. `skills/second-brain/package/` and installs it into a per-library virtualenv on
  130. first use (`python3 -m venv` + `pip install`); it needs Python 3.11+ and, for
  131. PDF ingestion, the optional `marker` OCR dependency.
  132. - **`lean-prover`** needs a working Lean 4 toolchain (`lean` and `lake` on `PATH`);
  133. it pins the toolchain per workstream and builds against mathlib. Without it the
  134. agent blocks the workstream cleanly rather than faking a proof. Every other agent
  135. runs with no extra tooling.
  136. ## Contributing
  137. Issues and PRs welcome — bug reports, new skills, a sharper proof discipline, or
  138. fixes to the ones here. No CLA and no ceremony.
  139. The toolbox grows the Linux way: a small core, plus self-contained **modules**
  140. (skills, agents, case studies). You don't need the whole tree — just the contract for
  141. the kind of module you're adding:
  142. - **[`CONTRIBUTING.md`](CONTRIBUTING.md)** — the module contract: where a skill/agent
  143. lives, its frontmatter, and the *no-hand-waving* bar your PR is reviewed against.
  144. - **[`ROADMAP.md`](ROADMAP.md)** — where it's headed and which modules are most wanted next.
  145. - **[Discussions](../../discussions)** — questions, prompt-sharing, ideas (lower-stakes than issues).
  146. - **[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)** — be rigorous about ideas, kind to people.
  147. New here? Try a [`good first issue`](../../issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
  148. or weigh in on the pinned roadmap RFC.
  149. ## Author
  150. Moran Koren, Ben-Gurion University of the Negev — korenmor@bgu.ac.il.
  151. If you use the toolbox in research, a mention is appreciated.
  152. ## License
  153. MIT. See `LICENSE`. Use them, fork them, tell me what broke.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.