### Complete Agent Workflow Example

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Demonstrates a full agent workflow including setup, observation, navigation, waiting, terminal execution, parallel execution, OCR, and listen server interaction.

```bash
# 1. Setup: Create tmux session for terminal work
drive session create agent-1 --dir ~/projects/myapp
```

```bash
# 2. Observe: Screenshot Safari to see current state
steer see --app Safari --json
# {"snapshot":"snap001","app":"Safari","screenshot":"/tmp/steer/snap001.png","count":42,...}
```

```bash
# 3. Navigate: Click on URL bar and type
steer click --on T1                          # Click URL field
steer type "github.com/myrepo" --clear       # Type URL
steer hotkey return                          # Press Enter
```

```bash
# 4. Wait: Poll for page load
steer wait --until-visible "README.md" --timeout 10
```

```bash
# 5. Terminal: Run git commands
drive run agent-1 "git clone https://github.com/myrepo"
drive run agent-1 "cd myrepo && npm install"
drive run agent-1 "npm test" --timeout 120
```

```bash
# 6. Parallel execution: Run tests across multiple environments
drive fanout "npm test" --targets node18,node20,node22
```

```bash
# 7. OCR: Extract text from Electron app (VS Code)
steer ocr --app "VS Code" --store
# snapshot: snap002
steer click --on "Run Tests" --snapshot snap002
```

```bash
# 8. Full automation via Listen server
just listen                                  # Start server (terminal 1)
just send "Clone the repo, run tests, and create a PR if tests pass"  # Submit job (terminal 2)
just latest                                  # Check job status
```

--------------------------------

### Project Setup

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Initializes the project environment by navigating to the directory and executing the setup script.

```bash
cd ~/Projects
chmod +x setup.sh
./setup.sh
cd steer
```

--------------------------------

### Install Steer CLI

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

Steps to build and install the Steer CLI tool from source.

```bash
cd steer
swift build -c release
cp .build/release/steer /usr/local/bin/
```

--------------------------------

### Automated Setup for Mac Mini Agent Sandbox

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Run this script directly on the Mac Mini to install all necessary dependencies, build the 'steer' CLI, set up Python environments, and run a verification suite.

```bash
/install-agent-sandbox
```

--------------------------------

### Automated Setup for Primary Engineer Device

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Run this script on your primary Mac to install the CLI client tools, configure the agent sandbox URL, and run a verification suite.

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

--------------------------------

### GET /jobs Response

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Example response listing all current jobs in the system.

```yaml
jobs:
- id: abc123
  status: completed
  prompt: "Open Safari and take a screenshot..."
  created_at: "2026-03-03T10:30:00Z"
- id: def456
  status: running
  prompt: "Run npm test in project X..."
  created_at: "2026-03-03T10:35:00Z"
```

--------------------------------

### Verify Help Command

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Displays the help menu to verify the installation and available subcommands.

```bash
.build/release/steer --help
```

--------------------------------

### Build and Verify Listen Service

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Steps to build the listen service by synchronizing dependencies and starting the server. The server runs on port 7600.

```bash
cd apps/listen
uv sync
```

```bash
uv run main.py
# → Uvicorn running on http://0.0.0.0:7600
```

--------------------------------

### Direct CLI - Listen Client: start

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Submits a new job prompt to the Listen server using the direct CLI client.

```APIDOC
## start - Submit New Job (Direct CLI)

### Description
Submits a new job prompt to the Listen server using the direct CLI client.

### Method
`uv run python main.py start` CLI command

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Command Examples
```bash
# Submit a job with explicit endpoint
cd apps/direct && uv run python main.py start http://localhost:7600 "Open Safari and search for Claude AI"

# Using configured endpoint (e.g., via 'just' command)
just send "Open Safari and navigate to github.com"
```

### Response Example
```
a1b2c3d4
```
```

--------------------------------

### Direct CLI Commands

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Provides commands for interacting with the agent server via its API. These include starting, getting status, listing, and stopping jobs.

```bash
python main.py start <url> "<prompt>"
```

```bash
python main.py get <url> <job_id>
```

```bash
python main.py list <url>
```

```bash
python main.py stop <url> <job_id>
```

--------------------------------

### JSON Mode Output Examples

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

Examples of JSON output from Steer commands, illustrating structured data for screenshots, accessibility trees, and action confirmations.

```json
{"snapshot":"a1b2c3d4","app":"Finder","screenshot":"/tmp/steer/a1b2c3d4.png","count":141,"elements":[...]}
```

```json
{"action":"click","x":450,"y":320,"label":"B3 \"Submit\"","ok":true}
```

```json
{"action":"type","text":"hello","ok":true}
```

--------------------------------

### Start Listen Server

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Starts the Listen HTTP server on port 7600. This server manages remote agent execution.

```bash
just listen
```

--------------------------------

### Example Pipeline Description

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Illustrates a cross-application pipeline combining browser interaction (OCR), terminal command execution, and logging to a knowledge base.

```text
Read GitHub issue (Browser via OCR) → Run Claude Code (Terminal via Drive) → Log result (Notion via Steer)
```

--------------------------------

### POST /job Request and Response

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Example JSON request to initiate a job and the corresponding response containing the job ID.

```json
{
  "prompt": "Open Safari and take a screenshot of the homepage"
}
```

```json
{
  "job_id": "abc123",
  "status": "running"
}
```

--------------------------------

### Agent Loop Example

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

Demonstrates a typical agent loop using Steer: observe the current state with 'see --json', perform an action with 'click' or 'type', and verify the result with another 'see --json'.

```bash
steer see --json          # 1. observe — screenshot + element map
```

```bash
steer click --on B3       # 2. act — click, type, hotkey
```

```bash
steer see --json          # 3. verify — see the result
```

--------------------------------

### Get Job Status via GET /job/{job_id}

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Retrieves job details including status, PID, and completion metadata.

```bash
# Get job status (returns YAML)
curl http://localhost:7600/job/a1b2c3d4
# Response:
# id: a1b2c3d4
# status: running
# prompt: Open Safari and navigate to news.ycombinator.com
# created_at: 2024-01-15T10:30:00Z
# pid: 12345
# session: job-a1b2c3d4
# updates: []
# summary: ""

# Check completed job
curl http://localhost:7600/job/a1b2c3d4
# Response:
# id: a1b2c3d4
# status: completed
# prompt: Open Safari and navigate to news.ycombinator.com
# created_at: 2024-01-15T10:30:00Z
# completed_at: 2024-01-15T10:32:15Z
# exit_code: 0
# duration_seconds: 135
```

--------------------------------

### Direct CLI - Listen Client: get

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Retrieves the current state of a job using the direct CLI client.

```APIDOC
## get - Get Job Status (Direct CLI)

### Description
Retrieves the current state of a job using the direct CLI client.

### Method
`uv run python main.py get` CLI command

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Command Examples
```bash
# Get job status
cd apps/direct && uv run python main.py get a1b2c3d4
```

### Response Example
```
{
  "id": "a1b2c3d4",
  "status": "running",
  "prompt": "Open Safari and search for Claude AI",
  "created_at": "2024-01-15T10:30:00Z"
}
```
```

--------------------------------

### Get Job Details

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Retrieves details for a specific job using the direct application or a 'just' command.

```bash
cd apps/direct && uv run python main.py get http://localhost:7600 a1b2c3d4
```

```bash
just job a1b2c3d4
```

--------------------------------

### GET /jobs

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

List all jobs currently managed by the server.

```APIDOC
## GET /jobs

### Description
List all jobs managed by the server.

### Method
GET

### Endpoint
/jobs

### Response
#### Success Response (200)
- **jobs** (array) - A list of job summaries.

#### Response Example
jobs:
- id: abc123
  status: completed
  prompt: "Open Safari and take a screenshot..."
  created_at: "2026-03-03T10:30:00Z"
- id: def456
  status: running
  prompt: "Run npm test in project X..."
  created_at: "2026-03-03T10:35:00Z"
```

--------------------------------

### List All Jobs via GET /jobs

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Lists active jobs by default. Use the archived query parameter to view past jobs.

```bash
# List active jobs
curl http://localhost:7600/jobs
# Response:
# jobs:
#   - id: a1b2c3d4
#     status: running
#     prompt: Open Safari...
#     created_at: 2024-01-15T10:30:00Z
#   - id: b2c3d4e5
#     status: completed
#     prompt: Run npm test...
#     created_at: 2024-01-15T10:25:00Z

# List archived jobs
curl "http://localhost:7600/jobs?archived=true"
```

--------------------------------

### Process List JSON Output

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

Example JSON output from 'drive proc list', detailing PID, parent PID, name, command, resource usage, and session.

```json
{
  "ok": true,
  "processes": [
    {
      "pid": 12345,
      "ppid": 1200,
      "name": "claude",
      "command": "claude --dangerously-skip-permissions ...",
      "cpu": 12.3,
      "memory_mb": 256,
      "elapsed": "5m32s",
      "session": "job-abc123"
    }
  ]
}
```

--------------------------------

### Process Resource Snapshot JSON Output

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

Example JSON output from 'drive proc top', providing details on PID, name, CPU usage, memory, thread count, elapsed time, and process state.

```json
{
  "ok": true,
  "snapshot": [
    {"pid": 12345, "name": "claude", "cpu": 45.2, "memory_mb": 512, "threads": 12, "elapsed": "12m05s", "state": "running"},
    {"pid": 12346, "name": "node", "cpu": 0.1, "memory_mb": 128, "threads": 4, "elapsed": "12m03s", "state": "sleeping"}
  ]
}
```

--------------------------------

### Core Process Operations in Python

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

These functions provide the core process management capabilities. Ensure psutil is installed for optimal performance.

```python
list_processes(name=None, parent=None, session=None) -> list[ProcessInfo]
kill_process(pid, signal=15, tree=False) -> KillResult
process_tree(pid) -> TreeNode
process_snapshot(pids) -> list[ProcessSnapshot]
session_pids(session_name) -> list[int]  # tmux pane PIDs + children
```

--------------------------------

### Get Resource Snapshot with Drive Proc

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

Use 'drive proc top' to obtain a single snapshot of resource usage (CPU, memory, threads, state) for specified PIDs or an entire session. Not a live monitor.

```bash
drive proc top --session job-abc123 --json       # Resource use for session procs
```

```bash
drive proc top --pid 12345,12346 --json          # Specific PIDs
```

--------------------------------

### GET /jobs - List All Jobs

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Lists all active jobs or archived jobs.

```APIDOC
## GET /jobs - List All Jobs

### Description
Lists all active jobs (or archived jobs with query parameter).

### Method
GET

### Endpoint
`/jobs`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **archived** (boolean) - Optional - If true, lists archived jobs.

#### Request Body
None

### Response
#### Success Response (200)
- **jobs** (array) - A list of job objects.
  - Each job object contains:
    - **id** (string) - The job ID.
    - **status** (string) - The job status.
    - **prompt** (string) - The job prompt.
    - **created_at** (string) - Timestamp when the job was created.

### Response Example (Active Jobs)
```yaml
jobs:
  - id: a1b2c3d4
    status: running
    prompt: Open Safari...
    created_at: 2024-01-15T10:30:00Z
  - id: b2c3d4e5
    status: completed
    prompt: Run npm test...
    created_at: 2024-01-15T10:25:00Z
```

### Response Example (Archived Jobs)
```yaml
jobs:
  - id: c3d4e5f6
    status: completed
    prompt: Archive test...
    created_at: 2024-01-14T09:00:00Z
```
```

--------------------------------

### Process Tree JSON Output

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

Example JSON output from 'drive proc tree', showing the root PID and a nested structure representing the process hierarchy.

```json
{
  "ok": true,
  "root": 12345,
  "tree": [
    {"pid": 12345, "name": "bash", "children": [
      {"pid": 12346, "name": "claude", "children": [
        {"pid": 12347, "name": "node", "children": []}
      ]}
    ]}
  ]
}
```

--------------------------------

### Get Display Information

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

The 'screens' command retrieves information about connected displays, including their resolution, origin, and scale factor. Use --json for structured output.

```bash
steer screens                    # list connected displays
```

```bash
steer screens --json             # with resolution, origin, scale factor
```

--------------------------------

### Get Latest Job Details via Direct CLI

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Retrieves full details of the most recent job from the Listen server using the Direct CLI client.

```bash
just latest
```

--------------------------------

### Get Last N Jobs Details via Direct CLI

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Retrieves full details of the last N jobs from the Listen server using the Direct CLI client.

```bash
just latest 3
```

--------------------------------

### Process Kill JSON Output

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

Example JSON output from 'drive proc kill', indicating the action taken, PIDs killed, signal used, and any PIDs that failed to be killed.

```json
{
  "ok": true,
  "action": "kill",
  "killed": [12345, 12346, 12347],
  "signal": 15,
  "failed": []
}
```

--------------------------------

### Visualize Process Tree with Drive Proc

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

Use 'drive proc tree' to display parent-child process relationships. Can start from a specific PID or the root PID of a tmux session. Output is a structured JSON representation of the tree.

```bash
drive proc tree 12345 --json                     # Tree from PID
```

```bash
drive proc tree --session job-abc123 --json      # Tree from session's root PID
```

--------------------------------

### Multi-Monitor Coordinate Translation

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

Steer handles coordinate translation for multi-monitor setups, automatically adjusting coordinates based on screen offset and scale factor when using the --screen flag with commands like 'click'.

```bash
steer screens
```

```bash
#  0  Built-in Retina Display  1728x1117  at (0,0)       scale:2.0 (main)
#  1  LG ULTRAWIDE             5120x1440  at (-1567,1117) scale:1.0
```

```bash
steer see --screen 1                          # capture specific display
```

```bash
steer click --x 500 --y 300 --screen 1       # auto-translates to global coords
```

--------------------------------

### Local Smoke Test Execution

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

A sequence of commands to perform a local smoke test. This involves starting the listen server, initiating a job via the direct CLI, checking its status, listing all jobs, and stopping a specific job.

```bash
# Terminal 1: start listen
cd apps/listen && uv run main.py

# Terminal 2: kick off a job
cd apps/direct && uv run main.py start http://localhost:7600 "echo hello from agent"

# Check status
uv run main.py get http://localhost:7600 <job_id>

# List all jobs
uv run main.py list http://localhost:7600

# Stop a job
uv run main.py stop http://localhost:7600 <job_id>
```

--------------------------------

### Application Management

Source: https://context7.com/disler/mac-mini-agent/llms.txt

List, launch, and activate applications on the system.

```bash
steer apps list
steer apps launch Safari
steer apps launch "Visual Studio Code"
steer apps launch Xcode
steer apps activate Safari
steer apps activate "VS Code"
steer apps list --json
```

--------------------------------

### GET /job/{job_id} - Get Job Status

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Retrieves the current state and details of a specific job.

```APIDOC
## GET /job/{job_id} - Get Job Status

### Description
Retrieves the current state and details of a specific job.

### Method
GET

### Endpoint
`/job/{job_id}`

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the job to retrieve status for.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **id** (string) - The job ID.
- **status** (string) - The current status of the job (e.g., "running", "completed").
- **prompt** (string) - The original prompt for the job.
- **created_at** (string) - Timestamp when the job was created.
- **completed_at** (string) - Timestamp when the job was completed (if applicable).
- **exit_code** (integer) - The exit code of the job (if completed).
- **duration_seconds** (integer) - The duration of the job in seconds (if completed).
- **pid** (integer) - The process ID of the worker.
- **session** (string) - The tmux session associated with the job.
- **updates** (array) - A list of updates for the job.
- **summary** (string) - A summary of the job's execution.

### Response Example (Running Job)
```yaml
id: a1b2c3d4
status: running
prompt: Open Safari and navigate to news.ycombinator.com
created_at: 2024-01-15T10:30:00Z
pid: 12345
session: job-a1b2c3d4
updates: []
summary: ""
```

### Response Example (Completed Job)
```yaml
id: a1b2c3d4
status: completed
prompt: Open Safari and navigate to news.ycombinator.com
created_at: 2024-01-15T10:30:00Z
completed_at: 2024-01-15T10:32:15Z
exit_code: 0
duration_seconds: 135
```
```

--------------------------------

### Build Project

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Compiles the project in release mode and verifies the binary existence.

```bash
swift build -c release 2>&1
```

--------------------------------

### Build and Verify Direct Service

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Steps to build the direct service by synchronizing its dependencies.

```bash
cd apps/direct
uv sync
```

--------------------------------

### POST /job

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Kick off a new agent job by providing a prompt.

```APIDOC
## POST /job

### Description
Kick off a new agent job. The server generates a job ID, creates a YAML state file, and spawns a worker process.

### Method
POST

### Endpoint
/job

### Request Body
- **prompt** (string) - Required - The task prompt for the agent.

### Request Example
{
  "prompt": "Open Safari and take a screenshot of the homepage"
}

### Response
#### Success Response (200)
- **job_id** (string) - The unique identifier for the job.
- **status** (string) - The initial status of the job (e.g., 'running').

#### Response Example
{
  "job_id": "abc123",
  "status": "running"
}
```

--------------------------------

### GET /job/{job_id}

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Read the current state of a specific job.

```APIDOC
## GET /job/{job_id}

### Description
Read current job state from the associated YAML file.

### Method
GET

### Endpoint
/job/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job.

### Response
#### Success Response (200)
- **YAML content** (object) - The raw YAML file contents for the job, including status, prompt, and results.

#### Response Example
id: abc123
status: completed
prompt: "Open Safari and take a screenshot of the homepage"
created_at: "2026-03-03T10:30:00Z"
completed_at: "2026-03-03T10:32:15Z"
duration_seconds: 135
pid: 12345
exit_code: 0
updates:
- "Launched Safari and navigated to homepage"
- "Captured screenshot and accessibility snapshot"
summary: |
  Opened Safari, captured the homepage accessibility tree (42 elements),
  and saved a screenshot to /tmp/steer/a1b2c3d4.png.
```

--------------------------------

### Integration Test

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Executes a full workflow of launching an app, capturing UI, clicking a button, and typing text.

```bash
.build/release/steer apps launch "TextEdit"
sleep 2
.build/release/steer see --app TextEdit --json > /tmp/steer_test.json

SCREENSHOT=$(python3 -c "import json; print(json.load(open('/tmp/steer_test.json'))['screenshot'])")
ls -la "$SCREENSHOT"

FIRST_BUTTON=$(python3 -c "
import json
d = json.load(open('/tmp/steer_test.json'))
buttons = [e for e in d['elements'] if e['role'] == 'button']
print(buttons[0]['id'] if buttons else 'NONE')
")
echo "First button: $FIRST_BUTTON"
if [ "$FIRST_BUTTON" != "NONE" ]; then
    .build/release/steer click --on "$FIRST_BUTTON"
fi

.build/release/steer type "steer integration test"
.build/release/steer see --app TextEdit
```

--------------------------------

### Focus Application

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Bring a specific application to the foreground.

```bash
steer focus Safari
steer focus "VS Code"
steer focus Terminal
```

--------------------------------

### List Applications

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Lists running applications in standard or JSON format.

```bash
.build/release/steer apps list
```

```bash
.build/release/steer apps list --json
```

--------------------------------

### Justfile for Agent Recipes

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

This justfile defines recipes for launching different agents (Claude and Pi) with a specified prompt and job ID. It ensures agents are run from the repo root and appends a system prompt.

```justfile
# apps/listen/justfile

# Launch an agent with the given prompt
# job_id is passed so the agent knows which YAML file to update
root := "../.."
sys_prompt := `cat ../../.claude/agents/listen-drive-and-steer-system-prompt.md`

# Launch Claude Code agent from repo root
agent-claude prompt job_id:
    cd {{root}} && claude --dangerously-skip-permissions \
      -p "{{prompt}}" \
      --append-system-prompt "{{replace(sys_prompt, '{{JOB_ID}}', job_id)}}"

# Launch Pi agent from repo root
agent-pi prompt job_id:
    cd {{root}} && pi -p "{{prompt}}" \
      --append-system-prompt "{{replace(sys_prompt, '{{JOB_ID}}', job_id)}}"

# Default agent (claude)
agent prompt job_id: (agent-claude prompt job_id)
```

--------------------------------

### Listen App Project Structure

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Directory layout for the listen application, including dependencies, server entry point, and job storage.

```text
apps/listen/
├── pyproject.toml       # uv-managed dependencies
├── main.py              # FastAPI app + server entry point
├── justfile             # Agent launch recipes
├── jobs/                # YAML job files (gitignored)
│   ├── abc123.yaml
│   └── def456.yaml
├── worker.py            # Subprocess worker — runs agent, updates yaml
└── .gitignore           # jobs/
```

--------------------------------

### Capture Screenshot of Frontmost App

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

Use the 'see' command to capture a screenshot of the frontmost application. For structured output usable by agents, use the --json flag.

```bash
steer see                        # frontmost app
```

```bash
steer see --app Safari           # target app by name
```

```bash
steer see --screen 1             # capture specific display
```

```bash
steer see --json                 # structured output for agents
```

--------------------------------

### Capture UI with Steer see

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Captures screenshots and accessibility trees for GUI automation. Use --ocr for Electron apps with empty accessibility trees.

```bash
# Screenshot frontmost app with element map
steer see
# Output:
# snapshot: a1b2c3d4
# app: Safari
# screenshot: /tmp/steer/a1b2c3d4.png
# elements: 47
#   B1     Button         "Back"  (10,50 40x40)
#   B2     Button         "Forward"  (55,50 40x40)
#   T1     TextField      "Search or enter website name"  (200,50 400x30)

# Target specific app with JSON output
steer see --app "VS Code" --json
# Output: {"snapshot":"b2c3d4e5","app":"VS Code","screenshot":"/tmp/steer/b2c3d4e5.png","count":12,"elements":[...]}

# Capture specific display (multi-monitor)
steer see --screen 1

# Filter elements by role
steer see --app Finder --role button

# Auto-OCR when accessibility tree is empty (Electron apps)
steer see --app Slack --ocr
```

--------------------------------

### Create Agent Job via POST /job

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Submits a prompt to the Listen server to spawn a worker process. Requires the server to be running.

```bash
# Start the Listen server
cd apps/listen && uv run python main.py
# Server runs on http://localhost:7600

# Submit a job via curl
curl -X POST http://localhost:7600/job \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Open Safari and navigate to news.ycombinator.com"}'
# Response: {"job_id": "a1b2c3d4", "status": "running"}

# Submit job with complex prompt
curl -X POST http://localhost:7600/job \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Run npm test in the project directory, then open the coverage report in Safari"}'
```

--------------------------------

### Manage Applications

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

The 'apps' command provides utilities for managing running applications, including listing them, launching new ones, and activating existing ones.

```bash
steer apps list                  # running apps with PIDs
```

```bash
steer apps launch Safari         # open an app
```

```bash
steer apps activate "VS Code"   # bring to front
```

--------------------------------

### Window Management

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Control application window positioning, sizing, and state.

```bash
steer window --app Safari move --x 100 --y 100
steer window --app Terminal resize --width 800 --height 600
steer window --app Finder minimize
```

--------------------------------

### Direct App Project Structure

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

Directory layout for the direct CLI client application.

```text
apps/direct/
├── pyproject.toml       # uv-managed dependencies
├── main.py              # Click CLI entry point
└── client.py            # HTTP client wrapper
```

--------------------------------

### Type Text

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Launches an application and types text into the active window.

```bash
.build/release/steer apps launch TextEdit
sleep 1
.build/release/steer type "hello from steer"
```

--------------------------------

### Observe-Kill-Verify Process Pattern

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

This sequence demonstrates a common workflow for managing processes: listing them, killing a specific process and its children, and then verifying that no related processes remain. Use the --json flag for machine-readable output.

```bash
1. drive proc list --session job-abc123 --json   → see what's running
2. drive proc kill 12345 --tree --json           → kill it and children
3. drive proc list --parent 12345 --json         → verify nothing survived
```

--------------------------------

### Submit New Job via Direct CLI

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Submits a job prompt to the Listen server using the direct client.

```bash
# Submit a job
cd apps/direct && uv run python main.py start http://localhost:7600 "Open Safari and search for Claude AI"
# Output: a1b2c3d4

# Using just command (configured endpoint)
just send "Open Safari and navigate to github.com"
```

--------------------------------

### apps - Application Management

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

Lists, launches, or activates applications.

```APIDOC
## apps

### Description
Manages application state including listing running apps, launching new ones, or bringing existing ones to the front.

### Parameters
#### Query Parameters
- **list** (command) - Optional - List running apps with PIDs.
- **launch** (string) - Optional - Launch an app by name.
- **activate** (string) - Optional - Bring an app to the front by name.
```

--------------------------------

### List All Jobs via Direct CLI

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Lists all submitted jobs managed by the Listen server using the Direct CLI client.

```bash
just jobs
```

--------------------------------

### Steer CLI - GUI Automation

Source: https://context7.com/disler/mac-mini-agent/llms.txt

The Steer CLI provides capabilities for GUI automation on macOS, including capturing screenshots, interacting with UI elements, typing text, and sending keyboard shortcuts.

```APIDOC
## Steer CLI - GUI Automation

The Steer CLI provides capabilities for GUI automation on macOS, including capturing screenshots, interacting with UI elements, typing text, and sending keyboard shortcuts.

### see - Capture Screenshot and Accessibility Tree

Captures a screenshot and extracts the accessibility tree from the target application. Returns element IDs (B1, T1, S1, etc.) that can be used with other commands. Supports filtering by role and automatic OCR fallback for Electron apps with empty accessibility trees.

#### Method
GET

#### Endpoint
/steer/see

#### Query Parameters
- **app** (string) - Optional - Target application name.
- **json** (boolean) - Optional - Output in JSON format.
- **screen** (integer) - Optional - Target display number.
- **role** (string) - Optional - Filter elements by role.
- **ocr** (boolean) - Optional - Enable OCR fallback for empty accessibility trees.

#### Request Example
```bash
steer see --app "VS Code" --json
```

#### Response
##### Success Response (200)
- **snapshot** (string) - Unique identifier for the snapshot.
- **app** (string) - Name of the target application.
- **screenshot** (string) - Path to the captured screenshot file.
- **count** (integer) - Number of elements found.
- **elements** (array) - List of UI elements with their properties.

##### Response Example
```json
{
  "snapshot": "b2c3d4e5",
  "app": "VS Code",
  "screenshot": "/tmp/steer/b2c3d4e5.png",
  "count": 12,
  "elements": [
    // ... element details
  ]
}
```

### click - Click Elements or Coordinates

Clicks on UI elements by element ID, label text, or screen coordinates. Supports double-click, right-click, middle-click, and modifier keys. Handles multi-monitor coordinate translation automatically.

#### Method
POST

#### Endpoint
/steer/click

#### Parameters
##### Query Parameters
- **on** (string) - Optional - Element ID or label text to click.
- **x** (integer) - Optional - X-coordinate for click.
- **y** (integer) - Optional - Y-coordinate for click.
- **double** (boolean) - Optional - Perform a double-click.
- **right** (boolean) - Optional - Perform a right-click.
- **modifier** (string) - Optional - Modifier keys (e.g., 'cmd', 'cmd+shift').
- **screen** (integer) - Optional - Target display number for coordinates.
- **json** (boolean) - Optional - Output in JSON format.

#### Request Example
```bash
steer click --on "Submit" --modifier cmd
steer click --x 100 --y 200 --screen 1
```

#### Response
##### Success Response (200)
- **action** (string) - The action performed ('click').
- **x** (integer) - The X-coordinate of the click.
- **y** (integer) - The Y-coordinate of the click.
- **label** (string) - The label or identifier of the clicked element.
- **ok** (boolean) - Indicates if the click was successful.

##### Response Example
```json
{
  "action": "click",
  "x": 450,
  "y": 320,
  "label": "B3 \"Submit\"",
  "ok": true
}
```

### type - Type Text into Applications

Types text into the focused application or a specific element. Can clear existing content before typing.

#### Method
POST

#### Endpoint
/steer/type

#### Parameters
##### Query Parameters
- **text** (string) - Required - The text to type.
- **into** (string) - Optional - Element ID to type into.
- **clear** (boolean) - Optional - Clear existing content before typing.
- **json** (boolean) - Optional - Output in JSON format.

#### Request Example
```bash
steer type "new value" --into T1 --clear
steer type "hello world"
```

#### Response
##### Success Response (200)
- **action** (string) - The action performed ('type').
- **text** (string) - The text that was typed.
- **ok** (boolean) - Indicates if the typing was successful.

##### Response Example
```json
{
  "action": "type",
  "text": "test",
  "ok": true
}
```

### hotkey - Send Keyboard Shortcuts

Sends keyboard shortcuts and key combinations to the active application.

#### Method
POST

#### Endpoint
/steer/hotkey

#### Parameters
##### Query Parameters
- **keys** (string) - Required - The key combination (e.g., 'cmd+s', 'return').

#### Request Example
```bash
steer hotkey cmd+s
steer hotkey cmd+shift+n
```

#### Response
##### Success Response (200)
- **action** (string) - The action performed ('hotkey').
- **keys** (string) - The key combination sent.
- **ok** (boolean) - Indicates if the hotkey was sent successfully.

##### Response Example
```json
{
  "action": "hotkey",
  "keys": "cmd+s",
  "ok": true
}
```

### ocr - Extract Text via OCR

Extracts text from screenshots using macOS Vision framework. Essential for Electron apps (VS Code, Slack, Notion) that expose empty accessibility trees.

#### Method
GET

#### Endpoint
/steer/ocr

#### Query Parameters
- **app** (string) - Optional - Target application name.

#### Request Example
```bash
steer ocr --app Safari
```

#### Response
##### Success Response (200)
- **app** (string) - Name of the target application.
- **text_regions** (integer) - Number of text regions detected.

##### Response Example
```json
{
  "app": "Safari",
  "text_regions": 23
}
```
```

--------------------------------

### Display Information

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Retrieve details about connected displays, including resolution and scale factors.

```bash
steer screens
steer screens --json
```

--------------------------------

### Hotkey Commands

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Simulates keyboard hotkey presses.

```bash
.build/release/steer hotkey cmd+a
.build/release/steer hotkey escape
```

--------------------------------

### Send a Job to the Agent

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Submits a natural language prompt to the agent for execution. The agent will interpret the prompt and perform the requested actions.

```bash
just send "Open Safari, navigate to news.ycombinator.com, and read the top 3 headlines"
```

--------------------------------

### Submit Job via Direct CLI

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Submits a job to the Listen server using the Direct CLI client. The job is defined by the provided string command.

```bash
just send "Open Safari..."
```

--------------------------------

### Input text with Steer type

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Types text into the focused application or a specific element, with optional clearing of existing content.

```bash
# Type into currently focused element
steer type "hello world"

# Click element first, then type
steer type "search query" --into T1

# Clear field before typing (select all + replace)
steer type "new value" --into T1 --clear

# Type special characters and longer text
steer type "user@example.com"
steer type "This is a longer message with punctuation!"

# JSON output
steer type "test" --json
# Output: {"action":"type","text":"test","ok":true}
```

--------------------------------

### Execute Hotkeys

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

The 'hotkey' command simulates key combinations, including standard shortcuts, modifier keys, and special keys like Return and Escape.

```bash
steer hotkey cmd+s
```

```bash
steer hotkey cmd+shift+n
```

```bash
steer hotkey return
```

```bash
steer hotkey escape
```

--------------------------------

### Locate UI Elements

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Search for UI elements based on text content or accessibility roles.

```bash
steer find --text "Submit"
steer find --text "Cancel"
steer find --role button
steer find --role textfield
```

--------------------------------

### Interact with UI using Steer click

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Simulates mouse clicks on elements, coordinates, or labels. Supports modifiers and multi-monitor translation.

```bash
# Click by element ID from latest snapshot
steer click --on B3

# Click by label text (fuzzy match)
steer click --on "Submit"
steer click --on "Save Changes"

# Click by coordinates
steer click --x 500 --y 300

# Double-click
steer click --on B3 --double

# Right-click (context menu)
steer click --on "file.txt" --right

# Click with modifier keys
steer click --on T1 --modifier cmd          # Cmd+Click
steer click --on B2 --modifier cmd+shift    # Cmd+Shift+Click

# Multi-monitor: click on screen 1 (auto-translates coordinates)
steer click --x 100 --y 200 --screen 1

# JSON output for agents
steer click --on B3 --json
# Output: {"action":"click","x":450,"y":320,"label":"B3 \"Submit\"","ok":true}
```

--------------------------------

### GUI Automation Commands

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Commands for controlling the GUI on macOS using the 'steer' CLI. Requires appropriate permissions like Accessibility and Screen Recording.

```bash
steer see --app Safari                    # Screenshot Safari
```

```bash
steer ocr --app "VS Code" --store         # OCR all text in VS Code
```

```bash
steer click --text "Submit"               # Click the "Submit" button
```

```bash
steer type "Hello, world"                 # Type text
```

--------------------------------

### System Clipboard

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Read from or write to the system clipboard.

```bash
steer clipboard read
steer clipboard write "text to copy"
```

--------------------------------

### System Prompt for Job Reporting

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/listen-and-direct-init.md

This markdown file is appended to the agent's system prompt. It instructs the agent on how to report progress updates and a final summary to its job YAML file using `yq`.

```markdown
## Job Reporting

You are running as job `{{JOB_ID}}`. Your job file is at `jobs/{{JOB_ID}}.yaml`.

### Progress Updates

Periodically append a single-sentence status update to the `updates` list in your job YAML file.
Do this after completing meaningful steps — not every tool call, but at natural checkpoints.

Example — read the file, append to the updates list, write it back:

```bash
# Use yq to append an update (keeps YAML valid)
yq -i '.updates += ["Set up test environment and installed dependencies"]' jobs/{{JOB_ID}}.yaml
```

### Summary

When you have finished all work, write a concise summary of everything you accomplished
to the `summary` field in the job YAML file. This is the last thing you do before exiting.

```bash
yq -i '.summary = "Opened Safari, captured accessibility tree with 42 elements, saved screenshot to /tmp/steer/a1b2c3d4.png"' jobs/{{JOB_ID}}.yaml
```
```

--------------------------------

### List Processes with Drive Proc

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/process_control.md

Use 'drive proc list' to view running processes. Filter by name, session, or parent PID. Output is JSON-native for easy parsing by agents. Defaults to current user's processes.

```bash
drive proc list --json                           # All user processes
```

```bash
drive proc list --name claude --json             # Filter by name substring
```

```bash
drive proc list --session job-abc123 --json      # Processes in a tmux session
```

```bash
drive proc list --parent 12345 --json            # Children of a PID
```

--------------------------------

### Archive All Jobs via POST /jobs/clear

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Moves all job data to the archive directory.

```bash
# Archive all jobs
curl -X POST http://localhost:7600/jobs/clear
# Response: {"archived": 5}
```

--------------------------------

### Send keyboard shortcuts with Steer hotkey

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Sends system-level keyboard shortcuts and special keys to the active application.

```bash
# Common shortcuts
steer hotkey cmd+s                  # Save
steer hotkey cmd+c                  # Copy
steer hotkey cmd+v                  # Paste
steer hotkey cmd+z                  # Undo
steer hotkey cmd+shift+z            # Redo
steer hotkey cmd+q                  # Quit app
steer hotkey cmd+w                  # Close window
steer hotkey cmd+tab                # Switch app

# Navigation
steer hotkey cmd+shift+n            # New folder (Finder)
steer hotkey cmd+t                  # New tab
steer hotkey cmd+shift+t            # Reopen closed tab

# Special keys
steer hotkey return                 # Enter
steer hotkey escape                 # Escape
steer hotkey space                  # Space
steer hotkey tab                    # Tab
steer hotkey delete                 # Delete
steer hotkey up                     # Arrow up
steer hotkey down                   # Arrow down
```

--------------------------------

### Manage Jobs

Source: https://github.com/disler/mac-mini-agent/blob/main/README.md

Commands to interact with the job queue and running jobs. Use 'just jobs' to list all jobs, 'just job <id>' to check a specific job's status, and 'just stop <id>' to terminate a running job.

```bash
just jobs              # List all jobs
```

```bash
just job <id>          # Check a specific job
```

```bash
just stop <id>         # Kill a running job
```

--------------------------------

### see - Capture Screen and Accessibility Tree

Source: https://github.com/disler/mac-mini-agent/blob/main/apps/steer/README.md

Captures a screenshot and the accessibility tree of the frontmost or targeted application.

```APIDOC
## see

### Description
Captures a screenshot and the accessibility tree of the frontmost or targeted application. Returns structured data when --json is used.

### Parameters
#### Query Parameters
- **--app** (string) - Optional - Target application by name.
- **--screen** (integer) - Optional - Capture a specific display index.
- **--json** (boolean) - Optional - Output structured JSON data.
```

--------------------------------

### Capture UI Elements

Source: https://github.com/disler/mac-mini-agent/blob/main/specs/init.md

Captures UI elements and screenshots, optionally filtered by application or output as JSON.

```bash
.build/release/steer see
```

```bash
.build/release/steer see --json
```

```bash
.build/release/steer see --app Finder
```

--------------------------------

### List All Jobs

Source: https://context7.com/disler/mac-mini-agent/llms.txt

Lists active or archived jobs. Use the --archived flag to view archived jobs. 'just jobs' provides a shortcut.

```bash
cd apps/direct && uv run python main.py list http://localhost:7600
```

```bash
cd apps/direct && uv run python main.py list http://localhost:7600 --archived
```

```bash
just jobs
```

```bash
just jobs --archived
```