1. In your terminal, run claude
2. In Claude Code, run the two install commands from the Claude Code section above
3. Open Cowork inside Claude Desktop. The plugin is already there.

Claude Desktop's chat UI doesn't support the plugin format yet, so use Cowork inside the same app for the full experience.

Configure API keys

The 5 free MCP servers (Skiplagged, Kiwi, Trivago, Ferryhopper, Airbnb) work immediately with zero keys. Cash flight and hotel search work out of the box.

To unlock award search and the rest of the toolkit, you need API keys set as environment variables in your shell. Run the local setup script:

macOS / Linux / WSL / Git Bash:

bash <(curl -fsSL https://raw.githubusercontent.com/borski/travel-hacking-toolkit/main/scripts/setup-keys.sh)

Windows (PowerShell):

iwr https://raw.githubusercontent.com/borski/travel-hacking-toolkit/main/scripts/setup-keys.ps1 -OutFile $env:TEMP\setup-keys.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\setup-keys.ps1
Remove-Item $env:TEMP\setup-keys.ps1

The script prompts for each key with masked input, validates them (rejects values with single quotes that would break the export, plus a per-key minimum length sanity check), writes them to the right shell rc with a backup, and never echoes the values back. The exports are single-quoted so other shell metacharacters in the key are safe. Keys never enter your terminal scrollback or any chat session. The /travel-hacker:getting-started skill inside Claude Code points at the same script.

The 4 highest-value keys:

| Key | What it unlocks | Cost | |-----|------|-----------| | SEATS_AERO_API_KEY | Award flight search across 27 mileage programs. The main event. | Pro ~$8/mo | | DUFFEL_API_KEY_LIVE | Real GDS cash flight prices. | Free to search, pay per booking | | IGNAV_API_KEY | Backup cash flight prices. Fast REST API. | 1,000 free requests/month | | AWARDWALLET_API_KEY + AWARDWALLET_USER_ID | Auto-pull your loyalty balances, elite status, transfer ratios. | Business account required |

Other keys (SerpAPI, RapidAPI, LiteAPI, TripAdvisor, RESROBOT, Rejseplanen, Entur) extend specific skills. The setup skill covers them too. See the full API key reference for signup links.

Five Docker-based skills (Southwest, American Airlines, Chase, Amex, TicketsAtWork) handle sites that don't have public APIs, plus a shared base image. They auto-pull on first use. See the Docker Images section for credentials and configuration.

Manual setup (if you'd rather not use the skill)

Add to your shell rc (~/.zshrc, ~/.bashrc, etc.):

export SEATS_AERO_API_KEY="your-key-here"
export DUFFEL_API_KEY_LIVE="your-key-here"
export IGNAV_API_KEY="your-key-here"
export AWARDWALLET_API_KEY="your-key-here"
export AWARDWALLET_USER_ID="your-user-id"

Reload (source ~/.zshrc) or open a new terminal, then run claude.

If you keep secrets in 1Password, you can resolve at launch instead:

op run --no-masking --env-file=.env -- claude

The --no-masking flag is required because op run's default output masking interferes with Claude Code's TTY detection and triggers a non-interactive prompt error. Masking only affects stdout, not the env vars themselves, so the keys still get to claude correctly.

(See 1Password CLI docs for the .env template syntax.)

The toolkit reads keys from the shell environment because plugin userConfig doesn't propagate to skills that shell out to scripts (verified empirically; related upstream issues anthropics/claude-code#11927, #39125).

Clone path (for OpenCode users or contributors)

OpenCode doesn't have a plugin format, so OpenCode users clone the repo. Contributors who want to hack on the toolkit also clone.

git clone https://github.com/borski/travel-hacking-toolkit.git
cd travel-hacking-toolkit

# macOS / Linux / WSL / Git Bash
./scripts/setup.sh

# Windows (PowerShell or cmd)
.\scripts\setup.cmd

The setup script picks your tool (OpenCode, Claude Code, Codex, or all three), creates your API key config file, installs dependencies, and optionally installs skills system-wide for OpenCode and Claude Code.

On Windows the .cmd wrapper launches scripts\setup.ps1 with an ExecutionPolicy bypass so nothing needs to be unblocked first.

Then launch your tool from inside the repo:

# OpenCode
opencode

# Claude Code (loads the plugin from the working tree, no install needed)
claude --plugin-dir .

# Codex
source .env && codex

claude --plugin-dir . loads the plugin (skills, MCP servers, and the travel-hacker subagent) directly from your clone. Changes you make to the toolkit are picked up immediately. Useful when you're contributing.

What's Included

MCP Servers (real-time tools)

| Server | What It Does | API Key | |--------|-------------|---------| | Skiplagged | Flight search with hidden city fares | None (free) | | Kiwi.com | Flights with virtual interlining (creative cross-airline routing) | None (free) | | Trivago | Hotel metasearch across booking sites | None (free) | | Ferryhopper | Ferry routes across 33 countries, 190+ operators | None (free) | | Airbnb | Search Airbnb listings, property details, pricing. Includes geocoding fix, property type filter, and DISABLE_GEOCODING opt-out. | None (free) | | LiteAPI | Hotel search with live rates and booking | LiteAPI |

Skills (API knowledge for your AI)

Start here: the orchestration skills call everything else automatically.

The skill tables below are auto-generated from skills/*/SKILL.md frontmatter by scripts/gen-skill-tables.sh. Edit the source frontmatter, not the tables. Signup links and API key URLs live in the API Keys & Signup Links section below.

Orchestration

| Skill | What It Does | API Key | |-------|-------------|---------| | award-calendar | Cheapest award dates for a route across a date range. Calendar grid view. | Seats.aero Pro | | compare-flights | Unified flight comparison across ALL sources in parallel. Auto-applies transfer optimization. | Uses individual skill keys | | compare-hotels | Unified hotel comparison across portals, metasearch, and Airbnb. FHR/Edit stacking detection. | Uses individual skill keys | | getting-started | First-run onboarding. Detects setup, points to setup-keys script, shows sample prompts. | None | | plan-trip | Guided trip planner. The hero command for the toolkit. | None | | trip-calculator | Cash vs points decision answered with math. Transfer ratios, taxes, opportunity cost. | None (free, local data) | | trip-planner | Full trip planning. Flights + hotels + points in one shot. | Uses individual skill keys |

Flights

| Skill | What It Does | API Key | |-------|-------------|---------| | duffel | Primary cash prices. Real GDS per-fare-class data. | Duffel | | google-flights | Browser-automated Google Flights. All airlines including Southwest. | None (requires agent-browser) | | ignav | Fast REST API cash prices. Market selection for arbitrage. | Ignav (1,000 free) | | seatmaps | Aircraft seat maps, cabin dimensions, seat recommendations. | None (requires agent-browser) | | seats-aero | Award availability across 27 mileage programs. | Seats.aero Pro/Partner | | southwest | SW fare classes, points pricing, Companion Pass. Change flight price drop monitor. Docker: ghcr.io/borski/sw-fares. | None (requires Patchright) | | wikipedia-airports | Route discovery and airline-service sanity check via Wikipedia airport