Local port registry for Codex

I have quite a few local projects, and many of them want to start something on localhost. Vite likes 5173, Astro likes 4321, Wrangler likes 8787, and databases have their own defaults.

This gets annoying when Codex is working across projects. It might start a dev server for one repo, then later another repo wants the same port. Here’s a low-tech fix for the problem. Tell Codex to maintain a registry for port allocations.

In my global AGENTS.md (~/.codex/AGENTS.md) I have this:

## Local port registry
Local project port allocations are tracked in `~/.config/ports/registry.md`.

Before starting dev servers, databases, fake APIs, or other local services, check this registry to avoid port conflicts across projects. If you assign, discover, or change a project's local port usage, update the registry in the same turn with the project name, absolute project folder, component, protocol, purpose, and source/reference. Do not remove another project's allocation unless the user explicitly asks.

The registry itself is just Markdown.

# Local Port Registry

## Allocated Local Ports

| Port | Project | Folder | Component | Protocol | Purpose | Source / Notes |
| ---: | --- | --- | --- | --- | --- | --- |
| 4321 | Personal blog | `~/Code/personal-blog` | Astro dev server | HTTP | Local website preview | `package.json` runs `astro dev`. |