DEV Community: PickAPlugin

How to write an AGENTS.md for Codex (with a starter template)

PickAPlugin — Mon, 09 Nov 2026 22:19:31 +0000

Disclosure: I run PickAPlugin, an independent catalog of ChatGPT and Codex plugins. This is adapted from our guide on the same topic.

AGENTS.md is a plain markdown file that Codex reads before it touches your repo. Think of it as the note you'd leave a new teammate on their first day.

What to put in it

How to install, run, test and lint, with the exact commands.
Code style rules that aren't obvious from the code.
What not to touch: generated files, secrets, migrations.
How you want PRs and commit messages written.

A starter template

# AGENTS.md

## Setup
- Install: `npm install`
- Dev server: `npm run dev`
- Tests: `npm test` (run before every commit)
- Lint: `npm run lint`

## Style
- TypeScript, strict mode. No `any` unless commented why.
- Prefer small functions and named exports.

## Don't touch
- `dist/` and other generated files
- `.env*` files and anything holding secrets
- `migrations/` unless the task is a migration

## PRs
- One focused change per PR.
- Commit messages: imperative mood, under 72 characters.

Where Codex looks

~/.codex/AGENTS.md holds global defaults.
Then Codex reads every AGENTS.md from the repo root down to your working folder. Closer files win.
AGENTS.override.md beats AGENTS.md in the same folder.
The combined size is capped at 32 KiB by default, so keep it tight.

Common questions

Do other tools read AGENTS.md? Yes, it's an open format. Cursor, Aider, Jules, Zed and others read it too.

Should I commit it? Yes, at the repo root, so everyone (and every agent) gets the same rules.

If you'd rather not start from a blank file, there's a free in-browser AGENTS.md generator that builds one from a few questions. The original guide is here.

How I vet a Codex plugin or MCP server in about two minutes

PickAPlugin — Wed, 04 Nov 2026 22:23:40 +0000

Plugins and MCP servers are easy to install, and that's the problem. A plugin can bundle hooks and MCP servers, and both run code on your machine. Nobody audits every community plugin (we don't either), so here's the quick check I run before installing anything.

Disclosure: I run PickAPlugin, an independent, hand-sorted catalog of ChatGPT and Codex plugins. This checklist is adapted from our guide, and it works no matter where you found the plugin.

1. Is it alive?

Look at the last commit, the open issues, and whether the repo is archived. A plugin that hasn't been touched in a long time may still work, but you'll be on your own when something in the host app changes.

2. What does it actually run?

Open .mcp.json and any hooks.json before you install. These are the parts that execute:

MCP servers start a process (often npx, uvx, or a binary) that your agent talks to.
Hooks run commands on events like tool calls or session start.

If you can't tell what a command does, look it up before letting it run.

3. What does it ask for?

Tokens, filesystem access, network access. Then ask whether that matches what it says it does. A Markdown formatter that wants your GitHub token deserves a closer look.

I boil this down to three questions:

What can it read?
What can it write or send?
Where does my data go?

If the README can't answer those on one screen, I usually skip it.

4. Who made it?

A known company or a maintainer with a history of active projects is a better bet than a brand-new account with one repo. It's not proof of anything, just a signal.

5. Is there a license?

No license means you technically can't reuse the code. It also tells you how much thought went into publishing it.

6. Is the manifest sane?

Check plugin.json for absolute paths, hardcoded secrets, or fields pointing somewhere unexpected. Those are red flags. We built a free plugin.json validator that catches the common problems in the browser.

What about official plugins?

Plugins in the built-in directory are curated by OpenAI, which is a real signal. It's still worth knowing what you're connecting, especially anything that touches email, files, or deploys.

The short version

Alive, what it runs, what it asks for, who made it, license, manifest. Two minutes, and you'll skip most of the sketchy stuff. The full checklist lives at pickaplugin.com/guides/vet-a-plugin.

What's on your own checklist? I'd like to hear what I'm missing.

I moved my MCP servers from Claude to Codex. Here's the cheat sheet

PickAPlugin — Mon, 02 Nov 2026 22:24:09 +0000

Full disclosure up front: I run PickAPlugin, a free directory of ChatGPT and Codex plugins, and I built a small converter while doing this move myself. You don't need it, though. Everything below works by hand.

Same servers, different wrapper

Claude Desktop and Cursor keep MCP servers in JSON. Codex keeps them in TOML, in ~/.codex/config.toml (or .codex/config.toml inside a trusted project). The servers themselves don't change at all. Only the config format does.

Here's a server in Claude's JSON:

{"mcpServers": {
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp"]
  }
}}

And the same server in Codex's TOML:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Each server becomes its own [mcp_servers.NAME] table. The CLI and the IDE extension both read the same file.

Things that bit me

env becomes an inline table. So "env": {"API_KEY": "..."} turns into env = { API_KEY = "..." }.
Remote servers use url. Put any headers in http_headers.
Keep tokens out of the file. For remote servers, bearer_token_env_var points Codex at an environment variable instead of pasting the token into config.toml.
You don't have to touch the server. Local stdio servers run the same command everywhere.

Or skip the file and use the CLI

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list

Where the old config lives

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

If you have a lot of them

Converting one or two by hand is fine. If you've got ten, I put a paste-and-convert page here: MCP config converter. It runs in your browser and nothing gets uploaded. It goes the other way too, TOML back to JSON.

The longer version of this guide is on pickaplugin.com.