# codex-agents

Claude Code plugin marketplace — 136+ specialized agents converted from [VoltAgent/awesome-codex-subagents](https://github.com/VoltAgent/awesome-codex-subagents).

## Install

```bash
# Add marketplace (one-time) in ~/.claude/settings.json → extraKnownMarketplaces:
# "codex-agents": { "source": { "source": "git", "url": "https://git.manticorum.com/cal/codex-agents.git" } }

# Update plugin index
claude plugin update codex-agents

# Install an agent
claude plugin install docker-expert@codex-agents --scope user
```

## Update from upstream

```bash
./sync.sh              # pull + convert (skips unchanged agents via SHA-256 hash)
./sync.sh --force      # re-convert all agents regardless of hash
./sync.sh --dry-run    # preview without writing
./sync.sh --verbose    # show per-agent status
```

## Agent Categories

| Category | Count | Examples |
|----------|-------|---------|
| Core Development | 12 | api-designer, frontend-developer, fullstack-developer |
| Language Specialists | 27 | python-pro, rust-engineer, typescript-pro, golang-pro |
| Infrastructure | 16 | docker-expert, kubernetes-specialist, terraform-engineer |
| Quality & Security | 16 | code-reviewer, security-auditor, penetration-tester |
| Data & AI | 12 | data-scientist, ml-engineer, prompt-engineer |
| Developer Experience | 13 | refactoring-specialist, cli-developer, mcp-developer |
| Specialized Domains | 12 | game-developer, fintech-engineer, blockchain-developer |
| Business & Product | 11 | product-manager, technical-writer, ux-researcher |
| Meta & Orchestration | 12 | multi-agent-coordinator, workflow-orchestrator |
| Research & Analysis | 7 | research-analyst, competitive-analyst, trend-analyst |

## How it works

`sync.sh` clones/pulls the upstream Codex repo, then `convert.py` transforms each TOML agent definition into a Claude Code plugin:

- **Model mapping**: `gpt-5.4` → `opus`, `gpt-5.3-codex-spark` → `sonnet`
- **Sandbox mapping**: `read-only` → tools without Edit/Write, `workspace-write` → full tools
- **Incremental**: SHA-256 hashes track which source files changed — unchanged agents are skipped
- **Cleanup**: Agents removed upstream are automatically deleted locally

Requires Python 3.11+ (uses `tomllib` from stdlib).