contacts-tools

A private, single-user tool that backs up the operator's own Google Contacts, keeps their contact labels tidy, and lets the operator's own assistant look a person up in that address book one at a time.

contacts-tools (until September 2026 named setup-google-contacts) works only with the operator's own Google Contacts. It takes a complete local backup of them, and it maintains the account's contact groups — the labels — declaratively: the groups that should exist are listed in a text file kept under version control, the tool shows the difference against the live account, and applies it only on an explicit confirmation.

It also serves the operator's own AI assistant in two ways. A short, hand-picked address book — names, nicknames and email addresses of the few people the operator has listed one by one in a configuration file — tells the assistant whom it may write to and through which address, so that “write to Kate” resolves correctly. And a lookup command answers a question about one named person at a time from the local backup — their email address, company, and on an explicit request their phone number — so the operator does not have to open their phone to find a number. The lookup is deliberately narrow: one person per query, a cap on the number of matches, no way to list the address book.

It is not a product and has no users other than its author. There is no sign-up, no hosted service and nobody else's account is ever touched. This page exists because Google requires an application using the People API to publish a home page and a privacy policy.

What it does

  1. Reads the contacts, contact groups and — on a Google Workspace account — the organisation's own directory profiles, and writes them to a backup file on the operator's machine. A weekly job on the operator's own server refreshes that backup.
  2. Compares the contact groups on the account with the list in the configuration file and shows the difference.
  3. On an explicit confirmation, creates or deletes contact groups so that the account matches the file. Deleting a group never deletes the contacts in it; the application does not create, modify or delete a single contact.
  4. Renders the hand-picked address book as a text file for the operator's own use, and reports when the label in Google Contacts that feeds it has drifted from the file.
  5. Answers a lookup for one named person from the local backup, for the operator's own assistant, on the operator's instruction.

Everything runs on the operator's own machines, started by hand or by a timer they configured. It is not a web service and accepts no inbound connections. Its source lives in a private repository.