Protocol Launcher

Tim ​

Tim is a macOS time tracker. Protocol Launcher allows you to generate Tim deep links.

Usage ​

There are two ways to use this library:

  • On-Demand import from subpaths enables tree-shaking and keeps bundles small.
  • Full Import from the root package is convenient but includes all app modules.

Pick On-Demand for production builds; Full Import is fine for quick scripts or demos.

Select Installation Method

On-Demand
Recommended. Optimized for production.
Full Import
Convenient. Good for quick scripts.

Notes ​

The current official help includes app/window navigation, task/group/record IDs, timer control, deprecated create links, and getCurrentUrl callbacks. createRecord() requires a task ID and ISO 8601 start/end dates. All create helpers are deprecated upstream. Nested callback URLs are percent-encoded.

Open Tim ​

On-Demand
ts
import { open } from 'protocol-launcher/tim'

const url = open()
Open Tim

Open Task Or Group ​

On-Demand
ts
import { openTaskOrGroup } from 'protocol-launcher/tim'

const url = openTaskOrGroup({
  id: 'D43FA035-6406-495D-9ADD-46721986040F',
})
Open Task Or Group

Start Task ​

On-Demand
ts
import { startTask } from 'protocol-launcher/tim'

const url = startTask({
  id: 'D43FA035-6406-495D-9ADD-46721986040F',
  notes: 'My Notes',
})

Stop Timer ​

On-Demand
ts
import { stopTimer } from 'protocol-launcher/tim'

const url = stopTimer()

Create Task ​

On-Demand
ts
import { createTask } from 'protocol-launcher/tim'

const url = createTask({
  title: 'My Title',
  notes: 'My Notes',
})

Create Group ​

On-Demand
ts
import { createGroup } from 'protocol-launcher/tim'

const url = createGroup({
  title: 'My Title',
  notes: 'My Notes',
})

Get Current URL ​

On-Demand
ts
import { getCurrentUrl } from 'protocol-launcher/tim'

const url = getCurrentUrl({
  xSuccess: 'https://www.apple.com',
})

Open Settings ​

Open the settings window.

On-Demand
ts
import { openSettings } from 'protocol-launcher/tim'

const url = openSettings()
Open Settings

Open Export ​

Open the export window.

On-Demand
ts
import { openExport } from 'protocol-launcher/tim'

const url = openExport()
Open Export

Open Upgrade ​

Open the upgrade window.

On-Demand
ts
import { openUpgrade } from 'protocol-launcher/tim'

const url = openUpgrade()
Open Upgrade

Create Record (Deprecated) ​

Create a time record for a task using ISO 8601 start/end dates. Tim marks create links as deprecated.

On-Demand
ts
import { createRecord } from 'protocol-launcher/tim'

const url = createRecord({
  'task': 'REPLACE_WITH_TASK_ID',
  'start': '2026-10-02T01:00:00Z',
  'end': '2026-10-02T02:00:00Z',
  'notes': 'Code review'
})

Generated URLs ​

ts
open()
// => 'tim://'

openTaskOrGroup({
  id: 'D43FA035-6406-495D-9ADD-46721986040F',
})
// => 'tim://D43FA035-6406-495D-9ADD-46721986040F'

startTask({
  id: 'D43FA035-6406-495D-9ADD-46721986040F',
  notes: 'My Notes',
})
// => 'tim://D43FA035-6406-495D-9ADD-46721986040F?action=start&notes=My%20Notes'

stopTimer()
// => 'tim://?action=stop'

createTask({
  title: 'My Title',
  notes: 'My Notes',
})
// => 'tim://create?type=task&title=My%20Title&notes=My%20Notes'

createGroup({
  title: 'My Title',
  notes: 'My Notes',
})
// => 'tim://create?type=group&title=My%20Title&notes=My%20Notes'

getCurrentUrl({
  xSuccess: 'https://www.apple.com',
})
// => 'tim://x-callback-url/getCurrentUrl?x-success=https%3A%2F%2Fwww.apple.com'

Official Documentation ​