Skip to main content

Train Commute Companion

HACS Custom Validate GitHub release PyPI Python Home Assistant License

Follows your train journey, a fixed train or any train in a time window, and tells you when something changes: a delay, a cancelled train, a platform change or a transfer you can no longer make.

Data: NS. You bring your own NS API key; none is bundled. This project is not made by or linked to NS.

Open your Home Assistant instance and open this repository in HACS.

What it does

You plan a fixed train, a time window or a minimum stay. It watches live train data, your phone and planned works. It rings for what matters, stays quiet for small changes and asks with one tap at another station.
  • Follows your trains. You describe your usual trips once, in a small YAML file. On a travel day it picks your train and watches it.
  • Tells you what changed. Delays, cancellations, platform changes, a train cut short, a new route, a transfer at risk or broken, and a train you missed.
  • Suggests what to do. When your train no longer works, it names the best train you can still catch.
  • Looks ahead. Before the day, it warns you about planned works on your route.
  • Summarizes the week. An optional works digest checks seven calendar days and labels unknown coverage.
  • Tracks replacement transport. Follow reviewed bus, walk and metro plans with explicit boarding and arrival confirmations. Replacement transport.
  • Shows crowd forecasts. NS forecasts appear with your trains and alternatives; changed forecasts can send silent updates. Crowd forecasts.
  • Changes plans and alerts. Resume a skipped journey and control quiet or paused notifications in Home Assistant.
  • Pauses for holidays. Set an inclusive date range and monitoring resumes afterward. Holiday pauses.
  • Uses weekday departure times. Set different first trains within one profile while preserving already-followed journeys. Schedules.
  • Follows any train in a time window. No usual train needed, with an optional minimum stay and settings per day. Schedules.
  • Notices another boarding station. With location on, it follows a known station by itself and asks once at a new one. Other boarding station.
  • Shows train context. Optional NS composition, listed capacity and candidate vehicle coordinates include source limits. Train context.
  • Loud only when it matters. Alerts you must not miss ring; small updates arrive silently.
  • Says when NS is unclear. When NS gives two different answers about the same train, you get both, so you can decide.

Ways to run it

Way What you get Guide
Home Assistant (HACS) Alerts on your phone through the companion app, sensors and buttons docs/home-assistant.md
Docker Alerts and buttons in a private Telegram chat docs/docker.md
Household A separate Docker companion and private bot for each traveller docs/household.md
Webhooks Each alert as signed JSON to your own URL, from Docker or Home Assistant docs/webhooks.md
Email Optional encrypted SMTP copies alongside Telegram in Docker docs/email.md
Today Private read-only journey and service status in a browser, from Docker docs/docker.md
MCP Three read-only tools (status, next connections, planned works) for a local MCP client docs/mcp.md

Location (optional) helps it know when you leave and where you are. See Where you are below.

Profiles can request accessible journeys and disable notification categories. These settings also appear in the Home Assistant profile form.

Save an explicit arrival to compare it with the original plan and optionally check NS compensation rules. The companion does not decide eligibility. Today also offers deliberate calendar and offline route-preview downloads.

Quick start (Home Assistant)

  1. In HACS, add https://github.com/rhnfzl/train-commute-companion as a custom repository of type Integration, or use the button above.
  2. Download Train Commute Companion and restart Home Assistant.
  3. Add the integration under Settings, Devices and services, and enter your NS API key.
  4. Enable guided setup to choose stations and trains in forms, or select an existing profiles file.

The full guide is in docs/home-assistant.md.

Where you are

A timetable app knows your train. It does not know where you are. With location on, the companion can:

  • see that you are still at home when your train leaves, and tell you the next train and when to leave;
  • see that you are on the train, so a late phone position does not cause a false "you missed it";
  • pick the next train you can catch when you leave home before your usual train leaves.
  • notice that you are at another station and follow a train from there, or ask you first.

Phones often report a position minutes late. A position just after the departure does not prove a miss. The companion also checks movement, Wi-Fi, activity and time:

When your train leaves: any sign you ride keeps the train followed. Still at home, work or the station with proof means you missed it, with the next train and when to leave. Without proof you get a quiet note. With no train followed near another station: a listed or remembered station is followed by itself, a new one asks Yes, Other train or No, then whether to remember it.

Activity counts only when reported after the departure and at most 5 minutes ago. Without proof the train stays followed, and you may get a quiet "has left. If you are not on it, next train" note. Regular train alerts still apply. Full rules: Missed trains and Other boarding station. Other sources: OwnTracks, Telegram.

Phone setup (Home Assistant companion app)

  1. Location: Always. iOS: Settings, Privacy & Security, Location Services, Home Assistant: Always, Precise Location on. Android: Allow all the time.
  2. Motion (optional, recommended). iOS: the app does not ask by itself. In the app open Settings, Companion App, Sensors, tap the blue Motion link and allow access, then enable Activity. Android: enable Detected activity. Details.
  3. Check it. In Home Assistant, Developer tools, States: your phone tracker has latitude and longitude, and the activity sensor is not unavailable.

Then add the location block to your profile. Steps and the optional Wi-Fi tracker: Location with Home Assistant.

The Python core

The core is a typed Python library on PyPI. It has no Home Assistant code.

It is released for its two shells, the Home Assistant integration and the Docker app, so its module APIs can change between versions. The supported entry point is the tcc command: check-profile, replay and run.

pip install train-commute-companion
tcc check-profile profiles.yaml

Development

uv run --extra app pytest -q        # core and app tests (the extra installs the MCP SDK)
uv run --extra app mypy src app/tcc_app
# the published floors: Python 3.12, httpx 0.27, PyYAML 6.0.1 and mcp 2.3
uv run --no-cache --isolated --no-project --python 3.12 --with '.[app]' --with httpx==0.27.0 --with PyYAML==6.0.1 --with mcp==2.3.0 --with pytest --with pytest-asyncio pytest -q tests tests_app
uv run ruff check src tests tests_ha tests_app tests_live custom_components app

# Home Assistant integration: Python 3.14.2+, in its own environment
export UV_PROJECT_ENVIRONMENT=.venv-ha
uv run --python 3.14 --group ha pytest tests_ha -q
uv run --python 3.14 --group ha mypy --explicit-package-bases --namespace-packages -p custom_components.train_commute_companion

The Validate workflow runs these same commands, and a release runs them before it publishes. Each night it also runs tests_ha against the newest Home Assistant test package, because the integration calls private mobile_app code.

Live NS checks run separately with your own key and capture alerts locally.

Diagrams

The pictures are Excalidraw drawings. To change one, open its .excalidraw file from docs/images in Excalidraw, edit it, and export the light and dark SVG again.

License

Apache-2.0

Metadata

Release files for train-commute-companion 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for train-commute-companion 0.4.0
File Size Uploaded Provenance Actions
train_commute_companion-0.4.0.tar.gz 1.3 MB With provenance Details for train_commute_companion-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for train-commute-companion 0.4.0
File Interpreter ABI Platform Actions
train_commute_companion-0.4.0-py3-none-any.whl Python 3 none any Details for train_commute_companion-0.4.0-py3-none-any.whl

Total release size: 1.6 MB

Release files / train_commute_companion-0.4.0.tar.gz

Download URL train_commute_companion-0.4.0.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
3d8c156fc35939c4b8451e3040b793ec43c32c288ac344229b4535f6e8a212b0
BLAKE2b-256 checksum
How to use checksums
4d3cd7f196ac3fa52c0979321b0f31bc3c396bff7d53e0a458e715cc1db28257
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / train_commute_companion-0.4.0-py3-none-any.whl

Download URL train_commute_companion-0.4.0-py3-none-any.whl
Size 272.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
acb1ed8fc851a8b1a256d0807879a5fc1030b2b847ddd280fb77ccdb35846bc8
BLAKE2b-256 checksum
How to use checksums
00d49fffb5dc6c0e9f5b4fa88482bc359989af50cd1b5451157400af0f675dea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for train-commute-companion 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for train_commute_companion-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page