Local ports

Every dev server your agents start listens on a port, and after a few chats it’s hard to remember which project is on localhost:3000 and which on 5173. Codz finds them for you: the Ports page lists each running project with its ports, and the menu bar keeps the first few one click away.

The Ports page

Open Ports from the account menu under your name, or press ⌘3. Codz scans when you open the page, keeps scanning every few seconds while it runs, and Scan now rescans at once.

The bar at the top says how many projects are running on how many ports, when the list was updated, and the Next free port with Copy.

Below it, Running projects groups the listeners by the folder the server runs in, stable endpoints first. Each project shows:

• Its name, taken from the folder. A generic folder name such as api, web or server is shown with its parent, like code / api.
• How many ports it has and its folder’s path.
• Open :5173, which opens the project’s main port in your browser.
• A row per port: the address, the program (such as Node.js or Python), its process ID, and Open and Copy.
• High-numbered worker ports tucked under internal ports, with Show and Hide.

A port marked Network is listening on all network interfaces, not just this Mac, so other devices on your network may reach it.

The … on a port row has Copy URL (or Copy address), Copy port number, Copy PORT=5173, Reveal project in Finder and, for a development server, Stop process….

Use Search ports to find a project, program, folder, port number or process ID.

What counts as a development server

Projects, the default, shows the listeners that look like development servers: web runtimes such as Node.js, Bun, Deno, Python, Ruby, PHP or Vite, anything running from a project folder in your home folder, and ports 3000 to 4999 that aren’t a known macOS service.

Switch to All to see every TCP listener your macOS account owns, including databases such as Postgres, MySQL, MongoDB and Redis and other background services. Codz never lists another user’s listeners.

Get a free port

The Next free port is the first port from 3000 to 3999 that nothing is listening on. Copy puts PORT=3001, for example, on the clipboard, ready for a terminal or a .env file. If every port in that range is taken, the bar says “Ports 3000–3999 are full”.

The menu bar offers the same thing as Free :3001.

Stop a server

1. Click … on the port’s row and choose Stop process….
2. Read the confirmation. It names the program and the address, lists any other ports the same process owns, and warns that unsaved server work may be lost.
3. Click Stop process with its process ID.

Codz sends the process a graceful stop signal, so it can shut down cleanly, and rescans. Only development servers offer Stop process….

If the listener changed between the scan and your click, Codz stops nothing and says “That listener changed or already stopped. Ports have been refreshed.” If macOS refuses the signal, the page shows “The process could not be stopped” with the system error.

In the menu bar and elsewhere

• The menu bar popover’s Local servers section lists the first three development servers. Click one to open it, or Manage for the Ports page.
• When the Browser panel has nothing open, it offers the running servers to open.
• codz ports prints the development servers, codz ports --all every listener, and --json adds each one’s port, process, project, folder, address, scope and URL. codz status includes the same list. See Commands.

codz ports
codz ports --all --json

Questions

My database isn’t listed. Databases aren’t development servers you open in a browser, so they’re under All, not Projects.

The list is empty and says “Port discovery requires /usr/sbin/lsof.” Codz finds listeners with macOS’s own lsof tool, which it expects at that path.

A server shows under a process name instead of a project. Codz couldn’t tell which folder the server runs in, so it groups it by process.