# mta-commuter

Adopt this skill: https://proskills.md/skills/other/ottomanelli-mta-commuter

Page: https://proskills.md/skills/other/ottomanelli-mta-commuter
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 6584
upstream: https://github.com/ottomanelli/mta-commuter/blob/HEAD/SKILL.md

````text
---
name: mta-commuter
description: >
  NYC commuter transit: LIRR, Metro-North, and Subway schedules, trip planning,
  and service alerts. Use when the user asks about train departures, arrivals,
  commute times, trip options, or service disruptions.
  Also for multi-leg trip planning between locations, finding nearby stations
  across all systems, alternatives to a specific train, or track alerts.
  Triggers on "LIRR", "Metro-North", "MNR", "subway", "train schedule",
  "train times", "train home", "get me to", "how do I get to", "trip from",
  "alternatives", "track alert", "nearby stations", "commute", "train options",
  "service alerts", "MTA".
version: 1.0.0
metadata:
  openclaw:
    emoji: "🚆"
    homepage: "https://github.com/ottomanelli/mta-commuter"
    requires:
      bins:
        - python3
    install:
      pip:
        - gtfs-realtime-bindings
---

## Instructions

Look up LIRR, Metro-North, and NYC Subway schedules with live delay data using `scripts/mta.py`. Uses MTA GTFS static feeds and GTFS-RT real-time APIs (no API key required). Requires the `gtfs-realtime-bindings` pip package (auto-installed via ClawHub; otherwise `pip install -r requirements.txt`).

Run from the skill directory (`skills/mta/`):

### Direct schedule lookup (LIRR or Metro-North)

```bash
python3 scripts/mta.py lirr "<origin>" "<destination>" --date YYYY-MM-DD --time HH:MM
python3 scripts/mta.py mnr "<origin>" "<destination>" --date YYYY-MM-DD --time HH:MM
```
- `--date` and `--time` default to now if omitted.
- Station names are fuzzy-matched. Common LIRR codes: NHP (New Hyde Park), NYK (Penn Station), JAM (Jamaica), ATL (Atlantic Terminal). Common MNR codes: GCT (Grand Central), WP (White Plains), HM (Harlem-125 St).
- Add `--json` for machine-readable output, `--count N` to change result count (default 5).
- Real-time delay data is automatically included for today's lookups. Use `--no-live` to show schedule only.

### Multi-leg trip planning

Plan trips across LIRR, Metro-North, and Subway connections. Uses `data/locations.json` for saved locations.

```bash
# Using saved locations
python3 scripts/mta.py trip --near-origin work --near-dest home --time 17:00

# Using coordinates
python3 scripts/mta.py trip --near-origin 40.75,-73.99 --near-dest 40.74,-73.68 --time 17:00

# Custom radius and count
python3 scripts/mta.py trip --near-origin work --near-dest home --time 17:00 --radius 2 --count 8
```

Trip planning finds commuter rail options from all systems and includes subway transfer legs where applicable (Penn Station, Grand Central, Atlantic Terminal, Jamaica, Woodside, Harlem-125 St).

### Find nearby stations (all systems)

```bash
python3 scripts/mta.py stations nearby --near home --radius 2
python3 scripts/mta.py stations nearby --lat 40.74 --lon -73.68
```

Returns LIRR, Metro-North, and Subway stations sorted by distance.

### Service alerts

```bash
python3 scripts/mta.py alerts                    # All systems
python3 scripts/mta.py alerts --system lirr       # LIRR only
python3 scripts/mta.py alerts --system mnr        # Metro-North only
python3 scripts/mta.py alerts --system subway     # Subway only
python3 scripts/mta.py alerts --json              # JSON output
```

### System-specific commands

```bash
python3 scripts/mta.py lirr --stations            # List all LIRR stations
python3 scripts/mta.py mnr --stations             # List all MNR stations
python3 scripts/mta.py lirr --routes              # List LIRR branches
python3 scripts/mta.py mnr --routes               # List MNR lines
python3 scripts/mta.py lirr --find-station "hyde"  # Search for a station
python3 scripts/mta.py lirr --alerts              # System-specific alerts
```

### Location management

Locations are stored in `data/locations.json`. Manage them conversationally:
- To add: geocode the user's address (via web search), then write to the JSON file directly
- To list: read and display the JSON file
- To update: modify the entry and rewrite the file

Format:
```json
{
  "home": {
    "address": "123 Main St, Anytown, NY 11000",
    "lat": 40.7432,
    "lon": -73.6812,
    "label": "Home"
  }
}
```

### Setup flow (first use)

When this skill is first activated and `data/locations.json` doesn't exist, ask the user:
1. "Where's home?" -- geocode the address via web search, save to locations.json
2. "Where's work?" -- same
3. "Any other places you travel to regularly?" -- save additional locations

After setup, when the user mentions a saved location, consider whether they might be asking about transit -- even without explicitly saying "train." For example, "how do I get home from the city" is a transit request if home is a saved location.

### Presenting trip results
- Highlight the best option (earliest arrival closest to target)
- Mention 2-3 alternatives with station distances
- For multi-leg trips, clearly show each leg (commuter rail + subway transfer)
- Note which branches/lines serve each option
- If there are relevant service alerts, check alerts and mention disruptions

### Track alerts

Watch for track announcements on LIRR or Metro-North trains using `scripts/check_track.py` via `openclaw cron`.

```bash
# LIRR track watch
openclaw cron add --every 20s \
  --command "cd skills/mta && python3 scripts/check_track.py --train 1582 --station NYK" \
  --channel telegram --delete-after-run \
  --name "Track watch: 5:22 PM to Huntington"

# Metro-North track watch
openclaw cron add --every 20s \
  --command "cd skills/mta && python3 scripts/check_track.py --system mnr --train 873 --station GCT" \
  --channel telegram --delete-after-run \
  --name "Track watch: 5:43 PM to White Plains"
```

**Note:** `check_track.py` queries undocumented endpoints used by the mylirr.org and mymnr.org web apps (`backend-unified.mylirr.org` / `backend-unified.mymnr.org`). These are not official public APIs and may change or become unavailable without notice. The rest of the skill uses the official MTA GTFS feeds and is not affected.

#### Workflow for "remind me about train X"

1. Look up the train to confirm it exists and get the departure time
2. Set up a cron job with `openclaw cron add` using the train number and `--system` flag
3. The cron job auto-deletes after the first notification (`--delete-after-run`)
4. Confirm the watch was added

### Limitations
1. **No subway real-time arrivals** -- subway frequency is estimated from schedule headways ("every ~8 min"), not live countdown data.
2. **No fares** -- cannot look up ticket prices.
3. **No bus** -- NJ Transit, MTA bus, and PATH are not included.

````

## File: README.md
upstream: https://github.com/ottomanelli/mta-commuter/blob/HEAD/README.md

````text
# mta-commuter — NYC Commuter Transit Skill

LIRR, Metro-North, and NYC Subway in one skill — with multi-leg trip planning across commuter rail and subway, live delays, and track-assignment watches.

Schedule lookup, multi-leg trip planning, and service alerts for the Long Island Rail Road (LIRR), Metro-North (MNR), and NYC Subway. Uses the MTA's public GTFS static feeds and GTFS-realtime APIs — no API key required.

## What it does

- **Schedule lookup** — LIRR and Metro-North trains between any two stations, with live delays
- **Multi-leg trip planning** — combines commuter rail with subway connections through major terminals (Penn, Grand Central, Atlantic Terminal, Jamaica, Woodside, Harlem-125 St)
- **Nearby stations** — finds the closest commuter rail and subway stations to a point
- **Service alerts** — current disruptions across all three systems
- **Track watch** — notifies you when a track is assigned to a specific train (via cron)

## Quickstart

```bash
# LIRR lookup
python3 scripts/mta.py lirr "Penn Station" "New Hyde Park" --time 17:00

# Metro-North lookup
python3 scripts/mta.py mnr "Grand Central" "White Plains" --time 17:00

# Multi-leg trip (saved locations in data/locations.json)
python3 scripts/mta.py trip --near-origin work --near-dest home --time 17:00

# Alerts
python3 scripts/mta.py alerts
```

See `SKILL.md` for the full command reference and agent-facing instructions.

## What you can ask your agent

Because the skill is triggered by natural-language intent (not just literal commands), you can talk to it the way you'd talk to a commuter friend who has the schedule memorized:

### Getting home / to work

> "When's the next train from Penn to Huntington?"
> "How do I get home from the office around 6?"
> "What time should I leave work to make the 5:22 out of Penn?"
> "Train options from Grand Central to White Plains tonight after 9."

### Multi-leg trips

> "Get me from home to the WTC by 9 AM."
> "What's the fastest way from Flatbush to Westchester?"
> "Plan a trip from my place to 34th and 8th — I can walk or take the train."

The planner combines LIRR or Metro-North with a subway transfer at the right terminal (Penn, Grand Central, Atlantic Terminal, Jamaica, Woodside, or Harlem-125 St) and picks the connection with the shortest total time.

### Finding alternatives

> "The 1582 got canceled — what are my options?"
> "Any other trains around 5:30 that can get me near Mineola?"
> "Give me alternatives that avoid the Port Jefferson branch."

### Nearby stations

> "What stations are near 40.74, -73.68?"
> "Closest subway to my hotel."
> "Are there any MNR stations within 2 miles of home?"

### Service alerts

> "Any LIRR alerts today?"
> "Is the 6 train running normal?"
> "What's broken on the MTA right now?"

### Track watch (set-and-forget notifications)

> "Ping me when track is posted for the 5:22 PM Huntington train."
> "Watch for the track on MNR 873 out of Grand Central."

The agent sets up an `openclaw cron` job that polls the track API every 20 seconds and auto-deletes itself after it fires once.

### First-time setup

On first use the agent can save your common locations so you don't have to repeat addresses:

> "Save home as 123 Main St, Queens NY."
> "My office is at 250 Broadway."

After that: "train home," "leaving work at 5," "how do I get from home to Dev's apartment" all resolve automatically.

## Install

```bash
pip install -r requirements.txt
```

Installing via ClawHub handles this automatically. The only runtime dependency is `gtfs-realtime-bindings`, used to decode the MTA's GTFS-realtime protobuf feeds for live delays and service alerts.

**First run:** the subway headway cache takes ~20-30 seconds to build the first time (it's processing ~2M stop_times rows). Subsequent invocations read from the cache and are instant. The cache invalidates automatically when the GTFS feed is refreshed (every 24h).

## Example output

**Schedule lookup:**

```
$ python3 scripts/mta.py lirr "Penn Station" "New Hyde Park" --time 17:00
LIRR trains from Penn Station to New Hyde Park
Monday 2026-04-13, at/after 5:00 PM
(with real-time data)

Depart     Arrive     Duration   Branch                    To
---------------------------------------------------------------------------
5:10 PM    5:42 PM    32min      Port Washington Branch    Port Washington
5:22 PM    5:53 PM    31min      Port Jefferson Branch     Huntington
5:37 PM    6:05 PM    28min      Ronkonkoma Branch         Ronkonkoma
```

**Multi-leg trip:**

```
$ python3 scripts/mta.py trip --near-origin home --near-dest wtc --time 08:00
Transit options from Home to World Trade Center
Departing after 8:00 AM

Option 1 (~52 min total):
  8:05 AM  LIRR New Hyde Park -> Penn Station (35min, Port Jefferson Branch)
  Walk to E train (4 min)
  E train to World Trade Center (~12min, ~every 5 min)
  Walk to destination (1 min)

Option 2 (~58 min total):
  8:17 AM  LIRR New Hyde Park -> Atlantic Terminal (41min, Hempstead Branch)
  Walk to 2/3/4/5 train (3 min)
  2 train to Chambers St (~10min, ~every 4 min)
  Walk to destination (4 min)
```

**JSON output** (for agents and pipelines):

```
$ python3 scripts/mta.py lirr NYK NHP --time 17:00 --json --count 1
[
  {
    "trip_id": "PJ-17-1582",
    "system": "lirr",
    "route": "Port Jefferson Branch",
    "headsign": "Huntington",
    "depart": 1042,
    "depart_str": "5:22 PM",
    "arrive": 1073,
    "arrive_str": "5:53 PM",
    "duration": 31,
    "origin": "Penn Station",
    "destination": "New Hyde Park",
    "status": "On time",
    "delay_min": 0
  }
]
```

## Layout

```
skills/mta/
├── SKILL.md              # Agent-facing instructions
├── README.md             # This file
├── scripts/
│   ├── mta.py            # Unified CLI entry point
│   ├── gtfs.py           # Generic GTFS loader with caching
│   ├── subway.py         # Subway station/line/headway layer
│   ├── trip.py           # Multi-leg trip planner
│   ├── geo.py            # Haversine + nearby-station search
│   ├── locations.py      # Saved locations loader
│   ├── check_track.py    # Track watch (mylirr/mymnr APIs)
│   ├── feeds.json        # GTFS feed URLs per system
│   └── transfers.json    # Terminal-to-subway transfer map
├── tests/                # pytest test suite
└── data/                 # GTFS cache + locations.json (gitignored)
```

## Tests

```bash
cd skills/mta
python3 -m pytest tests/ -v
```

## Data sources

- [MTA Developer Resources](https://new.mta.info/developers) — GTFS static and GTFS-realtime feeds
- Track watch uses the unofficial `backend-unified.mylirr.org` and `backend-unified.mymnr.org` endpoints that power the mylirr.org / mymnr.org web apps. These are not official public APIs and may change without notice.

## License

MIT-0 (MIT No Attribution). See `LICENSE`.

## Limitations

- No subway real-time arrivals (frequency is estimated from schedule headways)
- No fare information
- No bus, NJ Transit, or PATH coverage
````
