Train Commute Companion
Follows your usual NS train journey 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.
What it does
- 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.
- 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 |
| Webhooks | Each alert as signed JSON to your own URL, from Docker or Home Assistant | docs/webhooks.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: Home Assistant, OwnTracks, Telegram.
Quick start (Home Assistant)
- In HACS, add
https://github.com/rhnfzl/train-commute-companionas a custom repository of type Integration, or use the button above. - Download Train Commute Companion and restart Home Assistant.
- Copy examples/profiles.yaml to
<config>/train_commute_companion/profiles.yamland fill in your own stations and trains. - Add the integration under Settings, Devices and services, and enter your NS API key.
The full guide is in docs/home-assistant.md.
The Python core
The core is a typed Python library on PyPI. It has no Home Assistant code.
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 ruff check src tests
uv run mypy --strict src
License
Metadata
Release files for train-commute-companion 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| train_commute_companion-0.1.0.tar.gz | 697.7 kB | With provenance | Details for train_commute_companion-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| train_commute_companion-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for train_commute_companion-0.1.0-py3-none-any.whl |
Total release size: 841.4 kB
Release files / train_commute_companion-0.1.0.tar.gz
| Download URL | train_commute_companion-0.1.0.tar.gz |
|---|---|
| Size | 697.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
19a0154f578a6cace3eb8662c6be2848dab43cf8f3e4d002d9e8008b13842e9a
|
|
BLAKE2b-256 checksum How to use checksums |
e76c390a1ca1db4d3016e07750930d171b8860598caedd0cfd23455c7f43b25a
|
| 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 Oct 29, 2026.
Transparency logRelease files / train_commute_companion-0.1.0-py3-none-any.whl
| Download URL | train_commute_companion-0.1.0-py3-none-any.whl |
|---|---|
| Size | 143.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
15cc995a61e1c35f6b6ad1bd3944e5cb34a9faea62a4ce7918f155551c1e274b
|
|
BLAKE2b-256 checksum How to use checksums |
a1e2f81c1259f790b351e60a51bc6fbc56f3447da68cee9fc0fa42bac26fc03d
|
| 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 Oct 29, 2026.
Transparency logSecurity for train-commute-companion 0.1.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.
Attestation for train_commute_companion-0.1.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 Oct 29, 2026.
Transparency logA 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.