Why I built it
While running several coding-agent sessions on one Mac, I kept hitting a gap their UIs were not designed to answer: a task may be finished, but which processes, ports, browser helpers, services, or worktrees are still active—and which run owns them?
Answering that by hand means piecing together Activity Monitor, ps, lsof, launchctl, and
Git. It is slow, and a wrong guess can stop shared work or touch a dirty worktree. I wanted one
machine-level view that could show its evidence and be conservative enough to control what it
found.
What it does
Agent Ground Control is a native macOS menu-bar app and CLI that reconstructs ownership from local evidence. It combines process ancestry, loopback-port ownership, LaunchAgent state, browser helpers, worktree state, and narrowly scoped agent identity signals. When the evidence is incomplete, it says Unknown instead of guessing.
It can surface an orphan browser, a shared-port conflict, a stale local service, ambiguous
ownership, or a dirty worktree that must block cleanup. The app and agentctl CLI show the same
snapshots, findings, plans, and receipts.
Cleanup is intentionally conservative. Every eligible action starts with a preview and a
30-second single-use token. At confirmation time the daemon checks the machine again, sends
graceful SIGTERM only if identity and ownership still match, performs a post-action scan, and
stores an immutable receipt. Cleanup actions never use SIGKILL, delete user files or worktrees,
or edit agent configuration.
The included Demo Lab creates real but local fixtures for an orphan browser, a port conflict, a dirty worktree, and an adapter timeout. Judges can try detection, refusal, preview, cleanup, and receipts without an agent account, API key, or rebuild.
How I built it
The submitted build is native Swift for macOS 14 or later on Apple Silicon. An unprivileged per-user daemon collects read-only macOS evidence and feeds an evidence graph plus deterministic rules. One safety gate serves both the SwiftUI/AppKit app and CLI over a private Unix socket. SQLite stores privacy-reduced summaries and action receipts locally.
Codex, OpenClaw, and Hermes adapters can add identity evidence only through supported, trusted local surfaces. An adapter timeout or changed interface degrades that adapter to Unknown; it does not disable native observation or another adapter.
The package has no Electron runtime, web dashboard, root helper, kernel extension, system extension, cloud backend, or analytics service.
How I used Codex and GPT-5.6
Codex was my engineering workspace and multi-agent coordinator. I used it to explore the codebase and upstream agent interfaces, edit Swift modules, run builds and tests, and delegate independent spec, safety, performance, and packaging reviews. GPT-5.6 supplied the reasoning inside those Codex sessions: comparing product directions, challenging the fail-closed architecture, implementing test-first changes, investigating failures, and checking that fixes still matched the written design.
The most useful late catch happened after the unit tests were already green. The installed
LaunchAgent started the daemon in a context where CommandLine.arguments[0] could be relative,
so Demo Lab could not find its sibling executable inside the app bundle. Codex traced the failure
to executable-path discovery; the fix uses the kernel-reported executable path and adds a
regression test before rebuilding the submitted DMG.
Codex and GPT-5.6 are core build tools for this project, not runtime dependencies.
Why the runtime is deterministic
Process identity, port ownership, and worktree state are facts macOS can expose directly. I wanted the cleanup decision to be inspectable, reproducible, and able to refuse incomplete evidence. The shipped app therefore calls no LLM and requires no model key. It does not persist prompts, responses, reasoning, message history, environment variables, file contents, confirmation tokens, or raw adapter payloads.
The submitted Demo Lab runs locally with no agent login or internet connection. Observation summaries are retained for seven days and plans and receipts for thirty days, with an explicit local-data reset.
What was hard
The first challenge was ownership without reading conversations. A process name is not enough, so the graph combines start identity, ancestry, loopback listeners, service state, workspace evidence, and trusted adapter signals. Treating Unknown as a real product state was the key: if ownership cannot be proved, Ground Control shows the missing evidence and does nothing.
The second challenge was time-of-check versus time-of-use. A safe preview can become unsafe a second later. Plans therefore expire, tokens are single-use, and confirmation performs fresh PID/start-time, ownership, port, run-state, and worktree checks.
The third challenge was packaging a real per-user daemon. Code that worked from SwiftPM behaved
differently from /Applications under ServiceManagement. That forced me to test the actual app
bundle and DMG, including executable discovery, signatures, permissions, registration, teardown,
and residue—not just .build products.
Validation
The submitted evaluation build passed 397 XCTest cases and 67 Swift Testing cases with zero failures, including 22 package-layout checks. The release gate also exercises the packaged Demo Lab, privacy persistence, runtime network surfaces, artifact permissions, daemon teardown, and the exact mounted DMG layout.
In a five-minute qualification run against the submitted DMG, agentd averaged 0.327% CPU across
300 one-second samples; app plus daemon peak RSS was 95,895,552 bytes; and the DMG was 3,717,702
bytes (3.72 MB).
What I learned
Codex was most valuable at build time: it let me explore, implement, review, and retest much faster. At runtime, exact process identity and ownership are easier to audit when the decision path is deterministic. The most important product lesson was that Unknown is useful. A tool that controls machine resources should make missing evidence visible and decline to act.
Try it
The Build Week DMG is an ad-hoc-signed evaluation app, not a Developer ID-signed or Apple-notarized production release. It supports macOS 14 or later on Apple Silicon. After verifying the published SHA-256, macOS may require System Settings → Privacy & Security → Open Anyway on first launch.
Drag the app to /Applications, open Inspector → Settings, enable automatic daemon startup,
then start the simulated suite in Demo Lab. The repository includes a ten-minute no-rebuild
judge guide covering installation, refusal, one eligible cleanup, receipts, and teardown.
What's next
I want to add more evidence-backed findings and carefully versioned identity adapters without weakening the rule that Unknown and shared resources are never automatically cleaned up. A normal public release also needs Developer ID signing, notarization, broader hardware validation, and a clean-install test on a Mac with no prior Background Task Management history.
Log in or sign up for Devpost to join the conversation.