Amex TravelCAUTION

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: amex-travel
description: Search Amex travel portal for cash prices, MR points pricing, IAP discounts, and FHR/THC hotel benefits via Patchright. Use when comparing pay-with-points portal pricing to award alternatives.
category: portals
summary: Amex MR portal for flights, hotels, IAP discounts, FHR/THC benefits. Requires Platinum.
api_key: None (requires Patchright)
docker_image: ghcr.io/borski/amex-travel
---

# Amex Travel Portal Search

Search the American Express travel portal for flights and hotels via Patchright. Returns cash prices, MR points pricing, International Airline Program (IAP) discounts, and Fine Hotels & Resorts / The Hotel Collection benefits.

**Requires Patchright** (undetected Playwright fork). Amex blocks standard Playwright and agent-browser.

**Must run headed (headless=False).** Amex detects headless browsers. On macOS, a Chrome window briefly appears. For background operation, use Docker.

## Prerequisites

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

Or use Docker (no local install needed):
```bash
docker pull ghcr.io/borski/amex-travel:latest
# or build locally:
docker build -t amex-travel skills/amex-travel/
```

## When to Use

- Compare Amex portal MR pricing against cash and award prices
- Find IAP (International Airline Program) discounted fares on Platinum
- Find FHR and THC hotels with benefits ($100 credit, breakfast, upgrade)
- Compare portal redemption value against transfer-to-airline value

## When NOT to Use

- **Completing purchases.** Find flights and hotels only. Do not book.
- **Non-Platinum cards.** IAP fares and FHR benefits require the Platinum Card.

## Usage

### Flight Search

```bash
# Local (opens a Chrome window briefly)
python3 scripts/search_flights.py --origin SFO --dest CDG --depart 2026-08-11

# Round-trip business
python3 scripts/search_flights.py --origin SFO --dest CDG --depart 2026-08-11 --return 2026-09-02 --cabin business

# JSON output
python3 scripts/search_flights.py --origin SFO --dest CDG --depart 2026-08-11 --json

# Docker
docker run --rm \
    -v ~/.amex-travel-profiles:/profiles \
    -e AMEX_USERNAME -e AMEX_PASSWORD \
    amex-travel script /app/search_flights.py \
    --origin SFO --dest CDG --depart 2026-08-11 --cabin business --json
```

### Hotel Search

```bash
# Local
python3 scripts/search_flights.py --hotel --dest "Oslo" --checkin 2026-08-13 --checkout 2026-08-15

# Docker
docker run --rm \
    -v ~/.amex-travel-profiles:/profiles \
    -e AMEX_USERNAME -e AMEX_PASSWORD \
    amex-travel script /app/search_flights.py \
    --hotel --dest "Oslo" --checkin 2026-08-13 --checkout 2026-08-15 --json
```

### Record Mode (API Discovery)

Capture network traffic during a manual search:

```bash
python3 scripts/search_flights.py --record
```

### Offline Debug (Hotels)

Save and re-parse hotel results without re-running the browser:

```bash
# Save page HTML after hotel search
python3 scripts/search_flights.py --hotel --dest "Paris" --checkin 2026-08-11 --checkout 2026-08-15 --save-html /tmp/amex-hotels.json

# Re-parse locally (instant, no browser)
python3 scripts/search_flights.py --parse-html /tmp/amex-hotels.json
```

## 2FA Flow

Amex uses email OTP for 2FA. After first login with "Add This Device", subsequent runs skip 2FA from the same profile.

**How it works:** When 2FA is triggered, the script prints `2FA_CODE_NEEDED` to stdout and `2FA REQUIRED` to stderr, then polls for the code. It will wait up to 2 minutes.

**For agents:** When you see `2FA_CODE_NEEDED` in the script output, **ask the user** for the verification code Amex just emailed them. Once they provide it, write it to the code file:

```bash
echo "123456" > /tmp/amex-2fa-code.txt
```

The script picks up the file automatically and continues login.

**Command hook (optional, for full automation):** Set `AMEX_2FA_COMMAND` to a command that blocks until it has the code, then prints it to stdout. The script runs this instead of polling the file.

After first login with "Add This Device", 2FA is skipped on repeat runs from the same profile.

## Known Limitation: travel-portal login captcha (May 2026)

As of Amex's May 2026 overhaul, submitting a flight search redirects through a **separate travel-portal login gate** (`/account/travel/login`) — even when already signed in to americanexpress.com — protected by a **risk-based captcha layer**. The script fills and submits the gate automatically, and the outcome depends on how Amex scores the session that run:

- **Sometimes it passes** — the automated re-auth is accepted and results load end to end (verified live July 2026: full Docker run returned 50 parsed flights).
- **Sometimes it's silently swallowed** — fields hold the correct values after submit, the form's own `#loginSubmit` was clicked, no error renders, captcha markers sit in the DOM, and the page never advances. Also verified live, same day, same credentials, same container.

The travel session is also short-lived (next-auth token, ~1 hour), so warm sessions expire quickly and the gate re-appears often. On gate failure the script prints a `Gate diag:` line (field/button/alert state) so breakage is diagnosable from logs, then exits promptly instead of waiting out the results timeout. Hotel search may be affected similarly.

**The wall only exists on fresh logins.** With a warm saved session (valid cookies + trusted device), the gate passes automatically and searches work end to end. So the recovery is a one-time human step, not a dead end:

1. When the gate rejects the automated login (captcha or otherwise), the script prints **`AMEX_HUMAN_LOGIN_NEEDED`** to stdout (and writes `HUMAN_LOGIN_NEEDED` to `/tmp/amex-2fa-status.txt`). **For agents:** stop retrying and tell the user to run the refresh script. (A separate sentinel, **`AMEX_BAD_CREDENTIALS`**, means the credential env vars contained an unresolved secret-manager reference instead of real values — fix the credential injection, not the login.)
2. The user

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

What the source does

Filesystem

declared (2 observation(s))

Network

none-observed

Shell

declared (1 observation(s))

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills

.claude/skills

.opencode/skills

skills

AGENTS.md

Gates applied: no_behavioural_pass.