Coding agents waste 30 minutes rebuilding environments that are already running

Our coding agent was rebuilding entire Docker environments because it couldn't tell if containers were already running. Thirty minutes to spin up a dev environment that was already there.

The problem wasn't the agent's intelligence. It was treating every session like a fresh start.

Most coding agents are stateless by design. They wake up, assess the world from scratch, and start building. No memory of what they set up yesterday. No awareness of what's already running.

Here's what we built instead:

Session State Files

Three files that persist between agent sessions:

• ENVIRONMENT.md — What's running, what ports are open, what services are up
• SESSION_LOG.md — What the agent built in the last session
• NEXT_STEPS.md — What it was planning to do next

The agent reads these files before doing anything. Updates them as it works. Leaves breadcrumbs for its future self.

The Environment Check Pattern

1. Read ENVIRONMENT.md
2. Verify what's actually running (docker ps, lsof, ps aux)
3. Update the file with current state
4. Only build what's missing

Instead of docker-compose up --build every time, the agent runs docker-compose ps first. Checks if the database is already running. Sees if the API server is responding on port 3000.

If everything's up, it skips setup entirely.

The Session Handoff

When the agent finishes work, it writes a handoff note:

# Session Complete: 2024-01-15 14:30

## What I Built
- Added user authentication to /api/login
- Updated database schema (users table)
- Tests passing in auth.test.js

## Environment State
- Database: Running (port 5432)
- API Server: Running (port 3000) 
- Redis: Running (port 6379)

## Next Session Should
- Add password reset flow
- Update frontend login form
- Deploy to staging

The next session starts by reading this. No archaeological dig through git commits. No rebuilding working infrastructure.

The Verification Loop

The agent doesn't trust its own state files. It verifies:

• Process actually running? ps aux | grep postgres
• Port actually open? lsof -i :3000
• Service actually responding? curl localhost:3000/health

State files can lie. Process lists don't.

Why This Matters

Session continuity isn't just about speed. It's about not breaking working systems.

A stateless agent sees a running database and thinks "I should set this up." Runs migrations that have already run. Resets data that shouldn't be reset.

A stateful agent sees a running database and thinks "Good, that's handled. What's next?"

Pro tip: Put these state files in your .gitignore. They're runtime artifacts, not source code. Each developer's local environment state is different.

We went from 30-minute setup sessions to 30-second status checks. The agent spends its time building features, not rebuilding infrastructure.

Session state isn't glamorous. But it's the difference between an agent that helps and one that just burns tokens reconstructing the world every morning.