Mac Mini Agent

The Listen & Direct system enables remote agent execution across different machines over HTTP. It consists of two primary components:

1. apps/listen (The Server/Worker): A lightweight HTTP server and job manager that runs on the target machine (e.g., a Mac Mini). It accepts job requests, spawns autonomous worker processes that run agents (like Claude Code), and manages job state using YAML files on disk.
2. apps/direct (The CLI Client): A command-line interface used to interact with a listen server. It allows you to start, check, list, and stop jobs remotely.

Workflow:

• A client uses direct start to send a prompt to the listen server via POST /job.
• The server immediately returns a job_id and spawns a background worker.
• The worker executes the agent, which periodically updates a YAML file with progress and a final summary.
• The client polls GET /job/{job_id} to retrieve the job's current state and results.

Drive is a Python-based CLI (v0.1.0) that provides programmatic control over tmux sessions. It allows agents to create terminals, execute commands, and orchestrate parallel workloads.

Key Commands:

• session: Create, list, and manage tmux sessions.
• run: Execute a command in a tmux pane and wait for completion.
• send: Send keystrokes to a tmux pane.
• logs: Capture pane output using capture-pane.
• poll: Wait for a sentinel marker indicating command completion.
• fanout: Execute commands across multiple panes in parallel.

The Sentinel Pattern: To make asynchronous terminal orchestration deterministic, Drive uses a sentinel marker: __DONE_<token>:<exit_code>. This allows the agent to reliably detect when a command has finished instead of relying on guesswork.

# Create a new tmux session
drive session create --name agent-1

# Run a command and wait for it to finish
drive run --session agent-1 "npm test"

# Capture the output of a session
drive logs --session agent-1

# Run a command across multiple sessions in parallel
drive fanout --sessions a1,a2,a3 "build"

Your primary Mac (laptop) is used to send prompts and monitor jobs. It requires minimal dependencies (uv, just) and the CLI client tools.

Automated Installation

Run the installer on your primary Mac, providing the IP address or hostname of the Mac Mini sandbox:

/install-engineer-devbox <mac-mini-ip-or-hostname>

This command installs dependencies, configures the sandbox URL, and runs a 6-check verification suite (network connectivity, listen server, SSH access, and end-to-end job test).

Managing Jobs via CLI

After setup, use the following just commands to interact with the sandbox:

• just send "<prompt>": Send a new job to the agent.
• just jobs: List all active/past jobs.
• just job <id>: Check the status of a specific job.
• just stop <id>: Terminate a running job.

Debugging via SSH

If you need to debug the sandbox directly, you can SSH into the Mac Mini:

ssh <user>@<mac-mini-ip>
# or via Bonjour
ssh <user>@<hostname>.local

The Listen and Direct pair forms a job management system for remote agent execution.

Listen (Job Server)

A FastAPI-based Python server (v0.1.0) that accepts job requests over HTTP, spawns agents (like Claude Code) as worker processes, and tracks progress via YAML job files.

HTTP Endpoints:

• POST /job: Submit a prompt; returns a job ID.
• GET /job/{id}: Check job status, updates, and summary.
• GET /jobs: List all jobs.
• DELETE /job/{id}: Stop a running job.

Direct (CLI Client)

A Python CLI (v0.1.0) using httpx and Click to interact with the Listen server.

Direct Commands:

• start: Submit a new job prompt.
• get: Get current state of a job.
• list: List all jobs.
• latest: Show full details of the latest N jobs.
• stop: Stop a running job.

Workflow Example:

# Start the Listen server (typically on port 7600)
just listen

# Submit a job using Direct
just send "Open Safari..."

# Monitor jobs
just jobs
just job <id>
just latest

# Start server
just listen

# Submit a job
just send "Open Safari..."

# List all jobs
just jobs

# Check a specific job
just job <id>

# Get full details of the most recent job
just latest

The Mac Mini acts as the agent's workstation, running the Listen server and providing full GUI and terminal access.

Automated Installation

Run the following command directly on the Mac Mini to install dependencies (Swift, tmux, uv, just, yq, Claude Code), build steer, set up Python environments, and run a 10-check verification suite:

/install-agent-sandbox

Manual Permissions Required

You must manually grant the following permissions in System Settings for the agent to function correctly:

Starting the Server

Once installation is complete, start the agent server using just:

just listen    # Starts Listen on port 7600