SouthwestCAUTION

AI-powered travel hacking and search with cash, points, miles, and award flights. Drop-in skills and MCP servers for Claude, Codex, and OpenCode.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: southwest
description: Search Southwest Airlines fares and points pricing via Patchright browser automation. SW is not in any GDS or API. Covers all fare classes, Companion Pass value, and fare drop monitoring.
category: flights
summary: SW fare classes, points pricing, Companion Pass. Change flight price drop monitor.
api_key: None (requires Patchright)
docker_image: ghcr.io/borski/sw-fares
allowed-tools: Bash(python3 *), Bash(docker *)
---

# Southwest Airlines Search

Search southwest.com via Patchright (undetected Playwright fork). Southwest is the only major US airline not in any GDS, API, or flight search tool. This skill is the only way to get SW-specific data: fare classes, points pricing, and Companion Pass qualification.

**Requires Patchright** (undetected Playwright fork). Standard Playwright and agent-browser are detected and blocked by SW. Patchright patches the browser fingerprint to bypass detection.

**Must run headed (headless=False).** SW detects headless browsers even with Patchright. On macOS, a Chrome window briefly appears and closes. For background operation with no popup, use Docker:

```bash
# Search new flights (default, no login needed)
docker run --rm ghcr.io/borski/sw-fares --origin SJC --dest DEN --depart 2026-05-15
docker run --rm ghcr.io/borski/sw-fares --origin SJC --dest DEN --depart 2026-05-15 --return 2026-05-18 --points --json

# Check existing reservation for price drops (requires SW login)
docker run --rm -e SW_USERNAME -e SW_PASSWORD \
  ghcr.io/borski/sw-fares change --conf ABC123 --first Jane --last Doe --json

# List all upcoming trips
docker run --rm -e SW_USERNAME -e SW_PASSWORD \
  ghcr.io/borski/sw-fares change --list --json

# Build locally
docker build -t sw-fares skills/southwest/
```

The Docker image uses xvfb to create a virtual display inside the container. Patchright runs "headed" against xvfb, bypassing SW's headless detection without opening any windows on your machine.

```bash
# Install
pip install patchright && patchright install chromium

# Search cash fares
python3 scripts/search_fares.py --origin SJC --dest DEN --depart 2026-05-15

# Search cash + points
python3 scripts/search_fares.py --origin SJC --dest DEN --depart 2026-05-15 --return 2026-05-18 --points

# JSON output
python3 scripts/search_fares.py --origin SJC --dest DEN --depart 2026-05-15 --points --json
```

**Key implementation details learned the hard way:**
- Navigate to southwest.com homepage FIRST, then to the results URL. Direct URL without homepage warmup gets blocked.
- Use `fareType=POINTS` URL parameter for points pricing. Don't try to click the Points toggle on the page.
- Use a fresh persistent browser context (temp dir) each run to avoid fingerprint accumulation.
- Extract text from `[role='main']` NOT `<main>`. The `<main>` element contains the booking form. `[role='main']` contains the flight results.
- Flight blocks can be parsed by splitting on `# \d+` patterns and ending at `View seats`.
- Always dismiss the cookie banner first. It blocks interactions.

## Prerequisites

```bash
pip install patchright && patchright install chromium
```

Or use Docker (no local install needed):
```bash
# Pre-built image (fastest)
docker pull ghcr.io/borski/sw-fares:latest

# Or build locally
docker build -t sw-fares skills/southwest/
```

## When to Use

- User asks about Southwest flights or fares
- Need points pricing (not available anywhere else)
- Need fare class breakdown (Basic, Choice, Choice Preferred, Choice Extra)
- Calculating Companion Pass value
- Comparing SW points vs cash vs other airlines

## When NOT to Use

- **Just need SW cash prices**: Use google-flights skill instead (faster)
- **Completing purchases**: Find flights only. Do not book.
- **Non-Southwest airlines**: Use duffel, ignav, google-flights, or other skills

## Southwest Fare Classes

| Fare | Points | Cash | Companion Pass | Change/Cancel | Bags |
|------|--------|------|----------------|---------------|------|
| Basic (Wanna Get Away) | Lowest | Lowest | **NO** | Credit only | 2 free |
| Choice (Wanna Get Away Plus) | Low | Low | **YES** | Transferable credit | 2 free |
| Choice Preferred (Anytime) | High | High | **YES** | Refundable | 2 free |
| Choice Extra (Business Select) | Highest | Highest | **YES** | Refundable + priority | 2 free |

**Critical for Companion Pass:** Only Choice and above qualify. Basic does NOT. This changes the CPP math significantly.

## Companion Pass CPP Formula

When CP is in play, one ticket buys travel for two:

```
Total cash value = qualifying_fare_cash x 2 passengers
CPP = total_cash_value / total_points x 100
```

Always frame as "points bought $X of travel for 2 people."

## Search: Use the Script

**Do NOT try to automate the SW booking form manually.** It's fragile and the form's React state doesn't cooperate with browser automation. Use the script instead, which navigates directly to the results URL.

```bash
# Local (opens a Chrome window briefly)
python3 skills/southwest/scripts/search_fares.py --origin SJC --dest DEN --depart 2026-05-15

# With return date and points
python3 skills/southwest/scripts/search_fares.py --origin SJC --dest DEN --depart 2026-05-15 --return 2026-05-18 --points

# JSON output for programmatic use
python3 skills/southwest/scripts/search_fares.py --origin SJC --dest DEN --depart 2026-05-15 --points --json

# Docker (no Chrome window, no display needed)
docker run --rm ghcr.io/borski/sw-fares --origin SJC --dest DEN --depart 2026-05-15 --return 2026-05-18 --points
```

The script handles everything: homepage warmup, cookie dismissal, result extraction, points toggle.

## How the Script Works

1. Launches Patchright (undetected Playwright) in headed mode with a fresh browser profile
2. Visits southwest.com homepage first to establish a normal browsing session
3. Navigates to the results URL with `fareType=USD` for cash or `fareType=POINTS` for points
4. Waits 15 seconds for SW's React app to render flight data

CAUTIONgrade B · trust 86/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

UNDECLARED (4 observation(s))

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (9)

.agents/skills

.claude/skills

.opencode/skills

skills

shutil.rmtree(tmpdir, ignore_errors=True)

shutil.rmtree(tmpdir, ignore_errors=True)

shutil.rmtree(tmpdir, ignore_errors=True)

shutil.rmtree(tmpdir, ignore_errors=True)

AGENTS.md

Gates applied: no_behavioural_pass.