Back to articles

Case Study

The development environment changes before the code

When agents started servers across projects and branches, ports and traffic became hard to follow. This case study covers building dev-proxy, an open source local proxy that combines subdomain routing, a terminal traffic inspector, and peers across machines, along with the problems that came up while rebuilding the environment for multi-project development.

It started with losing track of ports

In the previous article, I covered running projects with different development principles side by side. This one is about a tool I ended up building while working that way.

Working with AI agents, the first thing to change was not the code but the development environment. Agents started servers across several projects and branches at once, so localhost ports multiplied quickly and I began losing track of which tab belonged to which service on which branch. I wanted one place to see the requests moving through those servers, and there wasn't one.

So I built dev-proxy. One proxy routes every project's services by subdomain, and one terminal shows their HTTP and WebSocket traffic together. It is published under the MIT license.

Loading diagram…
Every path goes through one proxy, and the subdomain selects the target. Whether a service lives in another project, a worktree, or on another machine, its requests appear in the same terminal.

It began as one project spread across worktrees

I didn't start with multiple projects. My first experiment was to spread one large project across git worktrees and develop it with several agents. That is why the early proxy started with routing per worktree.

The limits showed as worktrees multiplied. Worktree file sizes grew too large, and binary file conflicts became hard to manage. So I changed direction toward multi-project development.

The worktree routing from that period is still there. With worktreeConfig in place, one command creates a worktree and assigns its ports.

dev-proxy worktree create feature-auth
# runs git worktree add
# allocates ports: www=4101, data=4102
# writes .env.local: PORT=4101, DATA_PORT=4102
# runs the post-create hook: pnpm install

Requests to feature-auth--www.example.dev:3000 then go to port 4101.

Why I kept building after seeing portless

While I was in the middle of building, Vercel Labs released portless. Subdomain routing, per-worktree URLs, an agent-friendly CLI: it was solving my problem in almost the same way. Seeing Vercel work on the same question gave me confidence in the direction.

I kept going because I wanted two more things: routing and a traffic inspector in the same terminal, and one proxy that could tie together services scattered across several machines. Watching AI coding tools all ship as CLIs also made me want to build a TUI myself.

This isn't a claim that one tool is better. Those were the conditions my environment needed.

Configuration agents can read and edit

Agent friendliness got the most attention in the design. When starting a new project, I wanted "register this with dev-proxy" to be the whole request. That only works if an agent can tell where to read and what to edit. So a project's routes and worktree rules live together in one dev-proxy.config.mjs at the project root.

/** @type {import('@reopt-ai/dev-proxy').Config} */
export default {
  routes: {
    www: "http://localhost:3001",
    api: "http://localhost:4000",
    "*": "http://localhost:3001",
  },
};

It maps subdomains to local services and nothing else. * is the fallback for subdomains with no match.

I also separated who edits which file. Global settings and worktree state stay apart from the project config.

FileContentsEdited by
~/.dev-proxy/config.jsonDomain, ports, TLS, project listPeople or the CLI
dev-proxy.config.mjsThe project's routes and worktree rulesPeople or agents
.dev-proxy.worktrees.jsonPort map per worktreeThe CLI only

The proxy watches the config and updates worktree routing right away. A request to an unregistered worktree gets an offline error page rather than silently falling back to another service, which makes it less likely that a response from the wrong server is mistaken for a healthy one.

Setup can go to an agent as well. Add the skill with the command below and tell Claude Code "setup dev-proxy". It inspects the project structure, suggests routes, and generates the config files. When something is misconfigured, dev-proxy doctor checks network, DNS, and TLS status.

npx skills add reopt-ai/dev-proxy

Tying machines together with peers

From here on, the features are specific to my environment. I now use several local development machines to build projects in parallel. With peers, another machine can take over a specific subdomain.

# Run once on the peer. It prints a code and waits for the root to approve
dev-proxy peer join example.dev

# Claim the studio subdomain while pnpm dev runs
dev-proxy peer run studio --port 3001 -- pnpm dev

Approval happens in the root's TUI. No token is copied by hand, and the claim is released when the command exits.

TLS, the inspector, and hostnames stay on the root. A service can move to another machine without changing cookies, OAuth redirect URIs, or CORS allow-lists. With one proxy tying the machines together, I think less about what is running where.

The same URL on a phone

The other feature is wildcard DNS. Point *.dev.example.com at the proxy machine's LAN IP, and phones and tablets on the same network reach the same URLs directly, with no per-device hosts file edits.

With many projects in development, this makes it quick to test across several mobile devices, and I used it more often than I expected.

Every request in one terminal

With requests from every running project flowing through one terminal, I can see what an agent is calling and where it is stuck. Each request shows its method, status code, size, and latency, alongside WebSocket connection state. I can open headers, cookies, and query parameters, then replay a request or copy it as a curl command.

I only took care of a few agent-friendly design choices, and the local proxy problems I had been wrestling with mostly went away.

The TUI was harder than expected

The TUI is built with Ink and React, yet it felt different from building a web interface. Understanding how the terminal redraws dynamically in response to key input took time. Without the element-level separation of the web, changing one part of the interface often affected the whole screen. Having fewer automated testing tools than the web also made a big difference.

The proxy was one piece

Once it was built, I could see the proxy was only one piece of multi-project development. Running many streams of work at the same time meant optimizing builds, linting, CI, CD, and local caching from a different angle than before. With agents running builds and tests dozens of times concurrently, the environment had to be ready not to bottleneck. Issues I had never needed to consider kept coming up.

If you are starting multi-project development, these questions are a place to begin. They are examples of what to check, not results I measured.

AreaQuestion to check
RoutingDo people and agents reach the same service through the same URL?
TrafficCan you see the requests and failures from agents in one place?
Builds and testsCan several agents run them at once without blocking other work?
LintingDoes feedback still arrive in a reasonable time as projects multiply?
CI and CDCan the pipeline handle the increased volume of changes?
Local cacheDo results stay separate when tasks share a cache?

Connecting to the OCLS loop

Through the OCLS loop of reopt architecture, the development environment is also something to design.

OCLS phaseWhat this case raises
OWNWhich machine holds this subdomain right now? peer list shows the owner and reachability
CONTRACTAre the files agents may edit separate from the ones only the CLI touches?
LAYERDoes the app know only its assigned port, leaving the domain, TLS, and inspector to the proxy?
SHARPENDo the calls and failures seen in the terminal inform the next environment improvement?

Subdomain claims are a small application of responsibility partitioning, and the boundary around configuration files deals with the same problem as a module contract. For any resource agents share, code or not, someone needs to decide who can change what.

Limits of this case

This experience is tied to my environment. I built the tool for running several projects across several local machines. If you develop one service on one machine, you don't need this much setup.

I also didn't measure the effect. Saying the problems mostly went away describes how it felt, not a before-and-after comparison of time or error counts.

Clean URLs come with setup costs and things to watch.

  • Reaching a project from a phone requires wildcard DNS and a certificate the device trusts.
  • With public DNS, anyone can look up that *.dev.example.com points to a private IP, although only devices on your network can reach it.
  • Some routers block DNS answers that contain private IPs. In that case, allow the domain in the router.
  • Remote peers connect only over HTTPS, and apps on a peer must listen on 0.0.0.0, not only localhost.
  • When several machines claim the same subdomain, the last claim wins. If you suspect a conflict, check the owner with peer list.
  • Since the inspector exposes headers and cookies, check that no credentials are visible before sharing or recording your terminal.

Time spent outside the prompt

AI coding skill tends to bring prompts to mind. A large part of my time this year went into rebuilding environments like this one. I keep turning similar problems into tools, and developing them into services as well.

You can try dev-proxy with the commands below. The code and documentation are in the GitHub repository.

npm install -g @reopt-ai/dev-proxy
dev-proxy init
dev-proxy

Tags

dev-proxydeveloper-environmentmulti-projectgit-worktreeOCLS

Related patterns