android-timeline-home-assistant

Status: experimental. The server side is exercised end to end in CI against the real collector, but no physical Android phone has ever fed it. See Current limitations.

A Home Assistant app (formerly "add-on") that receives raw timestamped events from the android-timeline-termux collector, stores them immutably, derives versioned hourly and daily features, measures how much of each day was actually observed, publishes a handful of summary entities, and exposes a read-only MCP server so Claude can ask questions about the data.

What it does

• Authenticated ingestion. Device-specific bearer tokens, stored only as keyed hashes. Idempotent on event_id, so a replay is always a no-op.

• Immutable raw events. Features are derived and versioned; recomputing them never rewrites history.

• Explicit missingness. Every hour is a row, including the empty ones. A flat line and a dead collector are different things and are reported differently.

• Read-only MCP. No SQL, no shell, no filesystem, no mutation, no phone control. Bounded ranges, pagination, and redaction that cannot be turned off.

• Minimal privileges. Ingress only, no published port, no Supervisor role, no Home Assistant directory mounted.

Related MCP server: airspeed-mcp

Architecture

flowchart TD
    phone["Android phone<br/><i>android-timeline-termux</i>"]

    subgraph app["Home Assistant app (this repository)"]
        direction TB
        api["FastAPI ingestion<br/>POST /api/v1/events/batch"]
        auth["Device token auth<br/>+ rate limiting"]
        store[("SQLite event store<br/>append-only")]
        features["Feature pipeline<br/>hourly + daily, versioned"]
        cov["Coverage and gap detection"]
        tl["Timeline API<br/>GET /api/v1/timeline/yesterday"]
        mcp["Read-only MCP server<br/>/mcp"]
        ent["Summary entity publisher"]

        api --> auth --> store
        store --> features --> cov
        cov --> tl
        cov --> mcp
        features --> ent
    end

    ha["Home Assistant Core<br/>sensor.* / binary_sensor.*"]
    claude["Claude / MCP client"]

    phone -->|"HTTPS, Bearer token,<br/>X-Batch-ID"| api
    api -->|"per-event acknowledgement"| phone
    ent -->|"Supervisor API proxy"| ha
    mcp --> claude

Installation

1. In Home Assistant: Settings -> Apps -> App store -> ⋮ -> Repositories

2. Add https://github.com/resace3/android-timeline-home-assistant

3. Install Android Timeline from the store, then Start it.

4. Open the app's web UI (ingress) to reach the diagnostic page.

5. Enroll your phone:

   curl -X POST http://<app>/api/v1/admin/devices \
     -H 'Content-Type: application/json' \
     -d '{"device_id": "device-my-pixel-001"}'

   The response contains the device token once. Copy it into the collector's ~/.config/android-timeline/token. Only a keyed hash is stored here; there is no way to recover it later, only to rotate.

Full details, including running behind ingress and the optional custom integration: docs/installation.md.

Configuration

API

MCP

Twelve read-only tools: list_devices, list_phone_sources, get_phone_latest, query_phone_events, get_day_timeline, get_hourly_features, get_daily_features, get_data_coverage, find_data_gaps, get_collector_status, export_phone_window and describe_server.

Guaranteed absent: arbitrary SQL, shell execution, filesystem access, mutation of any kind, and phone control. Date ranges are capped at 31 days, pages at 1000 rows, and precise coordinates, message bodies and contact names are stripped with no parameter to re-enable them.

Client configuration (placeholders only): docs/mcp.md.

Testing

The cross-repository workflow installs the actual collector from android-timeline-termux at a pinned revision, runs its own outbox and uploader against a container built from this repository, then asserts on storage, idempotency, features, coverage and MCP. Details: docs/testing.md.

Current limitations

Stated plainly:

• No physical phone has ever fed this. Every event CI has ever ingested is synthetic.

• Supervisor is not tested in CI. A real Supervisor needs privileged Docker-in-Docker or a full OS image; a flaky green result would be worse than an honest gap. Layer B tests the one endpoint this app actually calls, and nothing more.

• Ingress trust is a design assumption. Treating an ingress request as an authenticated admin is only safe because no port is published. If you publish one, set admin_token and turn trust_ingress_admin off.

• SQLite, single writer. Fine for a personal deployment; not a fleet.

• Features are approximations. charging_minutes and wifi_connected_minutes are inferred from periodic samples, so a state change between samples is invisible. Every value ships with a coverage proportion for exactly this reason.

• The timeline has no polished UI. The / page is a diagnostic table.

Privacy considerations

• Raw events are stored as the phone sent them; the phone is where redaction happens, and it defaults to metadata only.

• The MCP server redacts precise coordinates, message bodies and contact names again on the way out, with no override.

• Home Assistant entities carry aggregates only, so the recorder database never accumulates behavioural detail.

• No fixture, test or CI artifact contains real personal data, and CI fails if a credential-shaped string appears anywhere in history.

Relationship to the other repository

This repository is the source of truth for the protocol schemas in schemas/. The collector vendors a byte-identical copy; the cross-repository workflow diffs them directly and fails on any difference. Both speak protocol_version 1. Compatibility policy: docs/data-model.md.

Development

python -m pip install -e ".[dev]"
ruff format . && ruff check . && mypy
pytest

Run the whole pipeline locally without Home Assistant:

docker compose -f test-harness/docker-compose.yml up --build

Roadmap

• Ingest from a real phone (blocking for 1.0)

• QR-code device enrollment

• A real timeline UI

• Optional Postgres backend for larger deployments

• Intervention annotations feeding the causal-inference use case

• Feature definitions v2 with dwell-time and place transitions

License

MIT