linear-gsuite

NPM Integrations Manual

minimal Linear and Google Workspace automation surface for calenderable actions

Install

npm install @tummycrypt/linear-gsuite

Languages

TypeScript 80.4% JavaScript 7.7% Nix 7.3% Just 2.6% Starlark 2.0%

README

linear-gsuite

Calendar automation engine that syncs Linear issues and recurring events into Google Calendar.

  • Syncs Linear issues with due dates as all-day calendar events
  • Syncs recurring operational events from JSON definitions
  • Automatically removes calendar events when issues are completed or canceled
  • Runs as a macOS launchd background agent or one-shot CLI
  • Declarative setup via Home Manager (NixOS / nix-darwin)

Quick start

# Install
pnpm install && pnpm build

# Authenticate with Google Calendar
linear-gsuite auth login --client-secrets-file ~/Downloads/client_secret_*.json

# Create a manifest (or use an example)
linear-gsuite doctor --config examples/tinyland-business-ops/linear-gsuite.package.json

# Sync
linear-gsuite calendar sync --config examples/tinyland-business-ops/linear-gsuite.package.json

Or via nix:

nix run github:tinyland-inc/linear-gsuite -- version

Documentation

Guide Description
Getting Started Install, authenticate, first sync
Authentication OAuth desktop flow, service accounts, _FILE secret pattern
Configuration Manifest schema, source types, identity keys
CLI Reference All commands, flags, output format
Home Manager Declarative NixOS/nix-darwin setup
Extending Adding new source adapters
Troubleshooting Common issues and diagnostics

Source types

Type Description
json-recurring-events Static recurring events from a JSON file
linear-issues Linear issues with due dates, auto-removed on completion

Install surfaces

Method Command
pnpm pnpm install && pnpm build && pnpm link --global
nix run nix run github:tinyland-inc/linear-gsuite -- <args>
nix develop nix develop for dev shell with all tooling
Home Manager Import homeManagerModules.default (guide)

Architecture

This repo is the engine. Consumer repos provide manifests.

Consumer repo                    linear-gsuite engine
├── linear-gsuite.package.json   → Source resolution
├── events.json                  → Google Calendar API (OAuth + service account)
└── business data                → Reconciliation, dedup, launchd lifecycle

The engine is source-agnostic: it syncs any ResolvedCalendarEvent[] regardless of origin. New source adapters only need to produce that type. See the Extending guide.

Example manifest

{
  "name": "my-calendar",
  "timezone": "America/New_York",
  "sources": [
    {
      "id": "recurring",
      "type": "json-recurring-events",
      "path": "./events.json"
    },
    {
      "id": "linear-due-soon",
      "type": "linear-issues",
      "apiKeyEnv": "LINEAR_API_KEY",
      "assignee": "me",
      "teamKey": "ENG",
      "dueWithinDays": 7
    }
  ]
}

Development

pnpm install
pnpm run typecheck   # type check
pnpm test            # vitest (13 tests)
pnpm run build       # compile to dist/
just status          # toolchain overview

CI runs typecheck, test, build, and publint on every PR.

License

MIT

lineargsuitecalendarautomation