One session per project: how my Claude Code agents stay on the job

Sun, 11 Oct 2026 20:00:00 +0000

I run a lot of small projects: websites, a trading-engine fork, a content publisher, the home lab itself. For a while each one meant opening a terminal, starting Claude Code, re-explaining where we were, and remembering to come back. The context lived in my head, which is exactly the place I'm trying to get it out of.

So now every project has one master session: a Claude Code session that belongs to that project, remembers it, and can be woken from anywhere, including my phone.

The whole interface is a text file

To wake a project's session, or give it a task, something drops a file into a requests folder:

folder=letsautom8
---prompt---
Work on letsautom8#4: shape the site as an engineering blog.
Follow "Working an issue". Report on the issue, not here.

A small launcher, a launchd agent on my Mac, notices the file and does one thing: it ensures the session. If the project's session is running, the prompt is delivered to it. If it isn't (never started, crashed, Mac rebooted), it's started first and then gets the prompt. A status file comes back with the result and a snapshot of the screen.

That's deliberately boring. Anything that can write a file can drive it: me from a terminal, a script, a scheduled job, or another agent.

One conversation per project, pinned

The important word is master. Each project has one Claude Code conversation, pinned by its ID. When the session has to be restarted, the launcher resumes that exact conversation rather than starting fresh. There are no hand-over notes and no "here's where we were" summaries: the session simply carries on.

Sessions run in tmux, one window per project, with remote control switched on, so each one also shows up in the Claude app on my phone. I can read along or nudge it while I'm away from the desk.

A few rules keep this sane:

An allowlist. Only listed project folders can be started, and the list says which ones may run unattended and which must ask before acting. Anything near live money or a client's tenant always asks.
One process per conversation. Two Claude processes on the same conversation step on each other. So nothing else is allowed to start a session in a project the launcher manages.
Stopping isn't forgetting. action=stop ends the process but keeps the master; the next request resumes it.

The trap: macOS Local Network privacy

The first version worked perfectly in testing and then couldn't reach anything on my LAN.

macOS asks for Local Network permission per app that started the process, not per user. A tmux server started by launchd isn't an app you can grant anything to, so every session inside it silently lost access to machines on the home network. You get "No route to host", which looks like a network fault, but it isn't one.

The fix was to make sure the tmux server is always born from Terminal, which does have the permission. When no tmux server is running, the launcher opens a tiny bootstrap script in Terminal. That script starts the server with a keep-alive session, and every session started afterwards inherits Terminal's exemption.

Lesson: when an automated process can't reach the network but the same command works in your terminal, check who the process's ancestor is before you debug the network.

Letting an agent hand out work, carefully

The next step was letting my chief-of-staff agent (it triages my notes and tickets) hand issues to these sessions itself. That's powerful and slightly alarming, so its requests are marked as coming from it and get extra rules:

A cap on busy sessions. Its requests wait in the queue while two sessions are already busy. My own requests are never held.
A pause switch. Creating a PAUSE file holds all of its requests until I delete it.
Only ready work. It hands over only issues with no open decision, nothing blocking them, and no other session already working on them. Production work also needs an explicit "go" from me on the issue.

The sessions themselves follow one shared rule set: one issue per session, mark it Doing while working, ask me only for real decisions, and report on the issue, not in a chat I'll never scroll back through.

What changed

The work now lives in tickets and the sessions live in tmux, which leaves me the decisions. When I say "send that to its session" to my lab connector by voice, a request file gets written, a session wakes up with its whole history, and the result appears on the issue.

That connector, which lets Claude's phone app see and act on the lab, gets its own write-up.

Welcome to the lab

Sun, 11 Oct 2026 07:00:00 +0000

This site is my lab notebook.

I'm an automation engineer. I come from test automation, and these days most of what I build is AI agents and the pipelines around them. Outside of that I keep a small home lab where I try things on my own work first: agents that run my tasks, sessions that pick up tickets by themselves, a connector that lets me run the lab by voice from the car.

Some of it works. Some of it breaks in instructive ways. Both are worth writing down.

What you'll find here

Write-ups of how things work. The architecture, the moving parts, the trade-offs, and the trap I fell into along the way.
Experiments in progress. Things marked running aren't finished, and may change or get abandoned.
The occasional post-mortem. When something fails properly, I'd rather explain why than quietly delete it.

What you won't find

Live details. Write-ups describe how something is built, never where it runs: no hostnames, keys or client data. Posts about trading software are about the engineering only, never returns or "this strategy makes X%". None of it is financial advice.

The format isn't fixed

I haven't settled on a format, and I don't want to guess. If a kind of post is useful to you (deep dives, short notes, videos), tell me and I'll do more of it. The contact section is at the bottom of every page.

letsautom8 · lab notes