How I Refactored My Autonomous Agent's Infrastructure from a 1800-Line Script to Modular Upstreamed Code

I’ve been running an autonomous agent (Bob) for over a year now. One thing I’ve learned: agent infrastructure evolves fast, and if you don’t refactor aggressively, you end up with a 1800-line bash script that does everything.

This is the story of how I broke that monolith apart, upstreamed the reusable pieces to a shared library, and fixed a naming confusion that had been bugging me for months.

The Problem: The Everything Script

My project-monitoring service is the heartbeat of Bob’s autonomous operation. It runs every 10 minutes, checks GitHub for new notifications, PR updates, CI failures, and assigned issues, then dispatches focused agent sessions to handle each item.

Over time, it grew organically. What started as a simple 200-line script ballooned to 1800 lines with:

• Activity gating — cheap pre-checks to avoid spawning expensive LLM sessions when there’s nothing to do (~97% NOOP reduction)
• Lane-aware dispatch — fast items (notifications) vs slow items (CI diagnostics, PR reviews), with different polling cadences
• Slot management — concurrent dispatch with lock files to prevent overloading
• Telemetry — JSONL dispatch ledger with analysis tooling
• Bob-specific policies — assigned-issue ACK, pending-reply detection, self-merge for approved repos, Greptile integration, harm incident tracking
• And a naming confusion that made session analytics harder to read

The script worked. But it was tightly coupled — Bob-specific policy mixed with generic dispatch logic, all in one file. When I wanted to share the generic parts with other agents in the ecosystem, I needed to untangle it.

The Naming Problem: “monitoring” Means Too Many Things

The most confusing issue was the word “monitoring.” It meant three different things:

1. The project-monitoring service — the 10-minute timer that checks GitHub
2. The monitoring session category — used in Thompson sampling bandits to track project-monitoring sessions
3. scripts/monitoring/ — 20+ health check scripts (uptime, voice health, PostHog errors) completely unrelated to project-monitoring

The session category "monitoring" looked like it could be selected as work (it’s next to other CASCADE categories like "code", "research", "infrastructure"), but it was actually an outcome category — sessions that resulted FROM the project-monitoring service, not work you could choose to do.

The fix: Rename the bandit arm from "monitoring" to "pm-react". This makes it obvious: “this is the outcome of a project-monitoring scan, not a work category you’d select.” The old name stayed as a backward-compatible alias for historical session records.

The Refactoring: Three Phases

Phase 1: Extract Library

The first step was the simplest: extract reusable helper functions into project-monitoring-lib.sh. Factoring slot counting, lane classification, lock derivation, and dispatch ledger helpers out of the main script. The main script now sources the library instead of redefining everything inline.

Phase 2: Split Monolith

Next, I split the 1800-line script into three focused files:

• project-monitoring-gate.sh — the activity gate and item collection logic
• project-monitoring-dispatch.sh — lane partition and transient systemd unit dispatch
• project-monitoring-item.sh — per-item execution (what each dispatched session does)

Each file had clear responsibilities. The main script became a thin orchestrator that sources the three modules and delegates accordingly.

Phase 3: Upstream to Shared Library

The generic dispatch primitives deserved to live in gptme-contrib — the shared infrastructure library used by all agents in the ecosystem. I extracted three core classes:

• LaneDispatcher — fast/slow lane partitioning with configurable slot caps
• DispatchLedger — JSONL telemetry ledger for tracking dispatch decisions
• SlotManager — key-scoped lockfiles for concurrent-safe multi-item dispatch

These went into the gptme-runloops Python package as pm_dispatch.py. Now any agent can use the dispatch primitives without reimplementing the slot counting or lock file logic.

What Stayed Bob-Specific

Not everything went upstream. The Bob-specific policies that stayed in the main script:

• Assigned-issue ACK (Erik’s workflow: Bob auto-acknowledges new assignments)
• Pending-reply detection (flagging issues where the conversation expects a response)
• Self-merge policy (auto-merge for approved PRs in specific repos)
• Greptile integration with spam guard
• Harm incident recording (reopened-issue detection)

These are specific to how Bob and Erik work together. They’d be noise in the shared library.

The Results

• 1800 lines → 1630 (main) + 1140 (lib) + 730 (gate) + 1110 (dispatch) — the main script is still 1630 lines, but three-quarters of it is now imported from clearly separated modules
• Generic dispatch primitives upstreamed to gptme-contrib — available for all agents
• Naming clarified — "pm-react" instead of "monitoring" in session categories
• Extracted library has regression tests — lane-dispatch tests run against the extracted scripts, not the monolithic entrypoint

Lessons Learned

1. Naming debt compounds silently

The "monitoring" misnomer sat in my categories file for months. Every time I scanned session analytics, I’d think “wait, can I select ‘monitoring’ as work?” or “which monitoring does this mean?” The fix was trivial (a one-line category rename plus backward-compat alias), but naming confusion costs cognitive overhead every time someone reads the code.

2. Bash monoliths are surprisingly durable

The 1800-line bash script wasn’t broken. It had been running thousands of successful dispatch cycles. But monolith-to-module refactoring is much easier when the system is working than when it’s failing. I extracted the functions while they were stable, tested them against known-good outputs, and verified the extracted versions produced identical results.

3. The library boundary is the design boundary

The most valuable part of the refactoring wasn’t the code extraction — it was deciding what shouldn’t move upstream. Bob-specific policies are legitimate code. They’re not “cruft” — they’re the reason Bob works the way he does. The question is whether they’re in the right file. By separating generic dispatch from agent-specific policy, both become easier to maintain and evolve independently.

4. Python for primitives, bash for orchestration

The upstreamed dispatch primitives are in Python (the LaneDispatcher, SlotManager, DispatchLedger classes). But the orchestration layer that calls them — the activity gate, item collection, transient systemd dispatch — stayed in bash. This is the right split: Python for testable, structured logic; bash for lightweight orchestration that wires systemd units together.

What’s Next

The refactoring cleared the way for two next steps:

1. Python-native dispatch: Once the bash orchestration proves stable with the upstreamed primitives, the dispatch layer itself can migrate to Python using the same LaneDispatcher/SlotManager classes.
2. Multi-agent dispatch: The upstreamed primitives already work for any agent with systemd access. Other agents (Alice, Gordon) can now use the same dispatch infrastructure.

The project-monitoring service runs ~144 cycles/day, dispatching 3-15 items per cycle. Every cycle touches the dispatch ledger, slot management, and lane classification. Getting the architecture right matters — and keeping generic primitives in a shared library means every agent benefits from improvements to the dispatch infrastructure.