Support codex

Author: mathpluscode

.claude-plugin/marketplace.json

@@ -4,16 +4,19 @@
     "name": "Yunguan Fu"
   },
   "metadata": {
-    "description": "A bibliography toolkit for LaTeX — Claude Code plugin",
+    "description": "A bibliography toolkit for LaTeX, built as agent skills",
     "repository": "https://github.com/mathpluscode/bibtools",
     "homepage": "https://bib.tools"
   },
   "plugins": [
     {
       "name": "bibtools",
-      "source": "./",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
       "description": "A bibliography toolkit for LaTeX",
-      "version": "1.4.0",
+      "version": "1.5.0",
       "keywords": ["bibtex", "bibliography", "latex", "overleaf", "academic", "reference", "citation"],
       "category": "academic",
       "license": "MIT"

.claude-plugin/plugin.json

@@ -1,12 +1,13 @@
 {
   "name": "bibtools",
   "description": "A bibliography toolkit for LaTeX",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "author": {
     "name": "Yunguan Fu"
   },
   "repository": "https://github.com/mathpluscode/bibtools",
   "homepage": "https://bib.tools",
   "license": "MIT",
-  "keywords": ["bibtex", "bibliography", "latex", "overleaf", "academic", "reference", "citation"]
+  "keywords": ["bibtex", "bibliography", "latex", "overleaf", "academic", "reference", "citation"],
+  "skills": "./skills/"
 }

.codex/INSTALL.md

@@ -0,0 +1,40 @@
+# Installing bibtools for Codex
+
+Enable the `bibtidy` skill in Codex via native skill discovery.
+
+## Prerequisites
+
+- Git
+
+## Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/mathpluscode/bibtools.git ~/.codex/bibtools
+```
+
+2. Create the Codex skills symlink:
+
+```bash
+mkdir -p ~/.codex/skills
+ln -s ~/.codex/bibtools/skills/bibtidy ~/.codex/skills/bibtidy
+```
+
+3. Restart Codex so it discovers the new skill.
+
+## Verify
+
+```bash
+ls -la ~/.codex/skills/bibtidy
+```
+
+You should see a symlink pointing at `~/.codex/bibtools/skills/bibtidy`.
+
+## Updating
+
+```bash
+cd ~/.codex/bibtools && git pull
+```
+
+The skill updates immediately through the symlink. Restart Codex if it is already running.

.github/workflows/lint.yml .github/workflows/ci.yml.github/workflows/lint.yml renamed to .github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Lint and Test
 
 on:
   push:
@@ -24,3 +24,7 @@ jobs:
           python-version: "3.12"
       - uses: astral-sh/setup-uv@v5
       - run: uv run pytest tests/ -v
+      - name: Check docs/index.html is up to date
+        run: |
+          python docs/build.py
+          git diff --exit-code docs/index.html

.gitignore

@@ -207,7 +207,9 @@ marimo/_lsp/
 __marimo__/
 .idea/
 .claude/settings.local.json
-tests/bibtidy/fixtures/got.bib
+.uv-cache/
+tests/bibtidy/fixtures/got_cc.bib
+tests/bibtidy/fixtures/got_codex.bib
 *.bib.orig
 TODO.md
 .DS_Store

AGENTS.md

@@ -0,0 +1,40 @@
+# bibtools
+
+A bibliography toolkit for LaTeX, built as agent skills. Explore the repo to understand the project structure before making changes.
+
+## General principles
+
+Bias toward action. Do not spend excessive time exploring files or asking clarifying questions when the task is clear. Start implementing and iterate.
+
+## Code changes
+
+- When fixing bugs or implementing changes, do NOT fix things that aren't actually broken. If you're unsure whether something is a real bug, ask before implementing a fix. Never apply fixes for theoretical issues that can't occur in practice given the actual workflow.
+- When making changes, always check README.md and other documentation files for references that need updating. Check for hardcoded magic numbers that should use existing config values.
+
+## Code review
+
+When asked to do a code review, only flag real actionable issues. Do NOT over-engineer fixes or apply unnecessary changes. When in doubt, propose the fix and wait for user approval before implementing.
+
+## How it works
+
+### bibtidy
+
+In Claude Code, invoke with `/bibtidy refs.bib`. In Codex, ask it to use the `bibtidy` skill on a `.bib` file. The agent reads the file, dispatches parallel subagents to verify entries against Google Scholar and CrossRef (bundled `crossref.py`), then applies fixes sequentially with targeted edits. Every change includes the original entry commented out and one or more source URLs for verification.
+
+## Versioning
+
+Version is tracked in three files (`.claude-plugin/marketplace.json`, `.claude-plugin/plugin.json`, `pyproject.toml`). Update all three, then run `uv lock` to sync `uv.lock`.
+
+## Development
+
+The skill's tools live under `skills/bibtidy/tools/` in this repo. At runtime, determine which agent platform you are (Claude Code, Codex, etc.) and resolve the installed tools directory accordingly (e.g. `~/.claude/skills/bibtidy/tools` for Claude Code, `~/.codex/skills/bibtidy/tools` for Codex). To test local changes:
+
+- Run `./tests/run_bibtidy_cc_tests.sh` — this syncs local tools to `~/.claude/skills/bibtidy/` before invoking Claude
+- Run `./tests/run_bibtidy_codex_tests.sh` for the Codex end-to-end path
+- Unit tests only: `uv run pytest tests/`
+
+## Code style
+
+- Keep code and comments plain, direct, and easy to scan. Avoid decorative formatting or cleverness that does not add meaning.
+- Add comments only when they clarify intent, constraints, or a non-obvious choice. Skip comments that just restate the next line.
+- Prefer small shared helpers and simple structure over repeated logic.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CLAUDE.md

@@ -1,12 +1,12 @@
 # Privacy Policy
 
-**bibtools** is a Claude Code plugin — a bibliography toolkit for LaTeX. It does not collect, store, or transmit any personal data.
+**bibtools** is a bibliography toolkit for LaTeX, built as agent skills. It does not collect, store, or transmit any personal data.
 
 ## What bibtools does
 
 - Reads and edits `.bib` files on your local machine
 - Sends bibliographic metadata (paper titles, author names) to public APIs (CrossRef, Google Scholar) to verify reference accuracy
-- All processing happens locally within your Claude Code session
+- All processing happens locally within your agent session
 
 ## What bibtools does NOT do
 

PRIVACY.md

@@ -1,13 +1,17 @@
 # bibtools
 
-A bibliography toolkit for LaTeX, built as a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin.
+A bibliography toolkit for LaTeX, built as agent skills. Available for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Codex](https://openai.com/index/introducing-codex/).
 
-**[bibtidy](#bibtidy)** — Cross-check BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. Upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags semantic duplicates (e.g. a preprint and its published version cited separately).
+**[bibtidy](#bibtidy)** — Cross-check BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. Upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags duplicate entries.
 
 ![bibtidy demo](docs/bibtidy_demo.gif)
 
 ## Install
 
+Installation differs by platform. Claude Code uses the plugin marketplace; Codex uses native skill discovery.
+
+### Claude Code
+
 Add the marketplace in Claude Code:
 
 ```bash
@@ -26,13 +30,23 @@ Reload plugins:
 /reload-plugins
 ```
 
-## bibtidy
+### Codex
+
+Tell Codex:
 
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/mathpluscode/bibtools/main/.codex/INSTALL.md
 ```
-/bibtidy refs.bib
+
+## bibtidy
+
+```text
+Use bibtidy to validate and fix refs.bib
 ```
 
-bibtidy verifies each entry against [Google Scholar](https://scholar.google.com/) and [CrossRef](https://search.crossref.org/), fixes errors, and upgrades stale preprints to published versions. Every change includes the original entry commented out above so you can compare or revert, plus a `% bibtidy:` URL for verification. We recommend using git to track changes. If using [Overleaf](https://www.overleaf.com/), this can be done with [git sync](https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization). To remove bibtidy comments after review, ask Claude: "remove all bibtidy comments from refs.bib".
+Or in Claude Code, use the slash command: `/bibtidy refs.bib`
+
+bibtidy verifies each entry against [Google Scholar](https://scholar.google.com/) and [CrossRef](https://search.crossref.org/), fixes errors, and upgrades stale preprints to published versions. Every change includes the original entry commented out above so you can compare or revert, plus one or more `% bibtidy:` URL lines for verification. We recommend using git to track changes. If using [Overleaf](https://www.overleaf.com/), this can be done with [git sync](https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization). To remove bibtidy comments after review, ask your agent to remove all `bibtidy` comments from the file.
 
 Note that bibtidy assumes standard brace-style BibTeX like `@article{...}`. Parenthesized forms like `@article(...)` are not supported; convert them to brace style first.
 
@@ -294,15 +308,15 @@ After:
 
 ### General
 
-**Do I need Claude Code?**
+**Do I need a paid subscription?**
 
-Yes. bibtools is currently a Claude Code plugin only. If there's demand to support other platforms (e.g. Codex), we'll consider adding it.
+Claude Code requires a paid plan (there is no free tier). Codex offers a free tier, so you can use bibtools with Codex at no cost.
 
-**Why a Claude Code plugin instead of a Python package?**
+**Why an agent skill/plugin instead of a Python package?**
 
-Building on Claude Code keeps the codebase small, the plugin reuses existing search and editing capabilities rather than reimplementing HTTP clients, parsers, and retry logic.
+Building on agent-native search and editing keeps the codebase small. The skill/plugin reuses existing web, editing, and subagent capabilities rather than reimplementing HTTP clients, parsers, and retry logic.
 
-bibtidy needs to search Google Scholar, CrossRef, and conference/journal sites. Google Scholar has no official API and bans scrapers; Semantic Scholar's public API (1,000 req/s) is shared globally so availability is unpredictable. Claude Code's built-in web search sidesteps both problems, no API keys, no shared rate limits. Citation metadata (title, authors, venue, year) is almost never behind a paywall, so Claude can simply visit the publisher page and read the correct information.
+bibtidy needs to search Google Scholar, CrossRef, and conference/journal sites. Google Scholar has no official API and bans scrapers; Semantic Scholar's public API (1,000 req/s) is shared globally so availability is unpredictable. Agent environments with built-in web access sidestep both problems, no API keys, no shared rate limits. Citation metadata (title, authors, venue, year) is almost never behind a paywall, so the agent can simply visit the publisher page and read the correct information.
 
 ### bibtidy
 
@@ -314,7 +328,7 @@ You shouldn't, and that's by design. The point of bibtidy is to surface potentia
 
 [CiteAudit](https://arxiv.org/abs/2602.23452) verifies bibliographic metadata but is a closed system. bibtidy is fully open-source, transparent (every change includes the original entry commented out and a source URL so you can verify exactly what changed and why), and it fixes issues (wrong authors, stale preprints, incorrect pages) directly in your .bib file rather than just flagging them.
 
-[refchecker](https://github.com/markrussinovich/refchecker) verifies references against Semantic Scholar, OpenAlex, and CrossRef, and uses LLM-powered web search to flag fabricated references. It reports problems but does not auto-fix them. bibtidy applies corrections in place so you review a diff, not a report. bibtidy also upgrades stale arXiv/bioRxiv preprints to their published versions (even when the title changed on publication), and requires no setup beyond installing the plugin.
+[refchecker](https://github.com/markrussinovich/refchecker) verifies references against Semantic Scholar, OpenAlex, and CrossRef, and uses LLM-powered web search to flag fabricated references. It reports problems but does not auto-fix them. bibtidy applies corrections in place so you review a diff, not a report. bibtidy also upgrades stale arXiv/bioRxiv preprints to their published versions (even when the title changed on publication), and requires no setup beyond installing the skill.
 
 [bibtex-tidy](https://github.com/FlamingTempura/bibtex-tidy) reformats and deduplicates .bib files but does not verify metadata against external sources. bibtidy checks correctness, not just formatting.