notion-workers

Notion Workers are small TypeScript programs hosted by Notion that add tools to Notion custom agents, sync external data into databases, and receive webhooks. These are the workers I use in my personal workspace.

Workers

Worker	What it does
twitter	Syncs Twitter bookmarks
readwise	Saves links to Readwise Reader to read or watch later
firecrawl	Fetches web pages as markdown or screenshots via Firecrawl
openlibrary	Looks up book cover image URLs by ISBN from OpenLibrary
pebble-index	Turns Pebble Index 01 ring voice notes into database pages via webhook

Using these workers yourself

Feel free to copy any worker into your own setup. The easiest way is to paste this prompt into your coding agent:

List the workers in https://github.com/colebemis/notion-workers and ask me
which ones I want. Copy those directories here and set them up as my own
Notion Workers: delete each workers.json (it points at the author's
workspace — my first deploy creates my own), help me install the ntn CLI
and run `ntn login` if I haven't, set the env vars listed in each
worker's README, then deploy each with `ntn workers deploy --name <name>`
and run one test call to verify.

Or by hand:

1. Copy the worker's directory.
2. Delete workers.json (it points at my workspace).
3. ntn login, add any required secrets (see the worker's README), then ntn workers deploy --name <name>.

Everything below is how I develop the workers in this repo.

Setup (once per machine)

curl -fsSL https://ntn.dev | bash   # install the ntn CLI
ntn login                           # authenticate with your Notion workspace

Requires Node ≥ 22.

Development workflow

Everything happens inside the worker's directory:

cd openlibrary
npm install                # first time only
npm run check              # type-check

Test a capability locally — this runs your code on your machine, auto-loading the worker's .env:

ntn workers exec getBookCover --local -d '{"isbn": "9780140328721", "size": null}'

Deploy (builds in the cloud and updates the worker that workers.json points at):

ntn workers deploy

Then verify the deployed version by dropping --local:

ntn workers exec getBookCover -d '{"isbn": "9780140328721", "size": null}'

Debugging a deployed worker:

ntn workers runs list            # recent runs
ntn workers runs logs <runId>    # logs for a run

Adding a new worker

./new-worker.sh my-worker

This runs ntn workers new and then deletes the boilerplate that already lives at the repo root (agent docs, LICENSE, ignore files), leaving a minimal project. Then:

1. Implement capabilities in my-worker/src/index.ts (see .agents/INSTRUCTIONS.md for the capability API).

2. Write a short README.md for the worker.

3. First deploy creates the worker and writes workers.json:

   cd my-worker
   ntn workers deploy --name my-worker

4. Commit everything, including workers.json.

To use a tool from a Notion custom agent, add it in the agent's tool settings in Notion.

Secrets

Secrets live in two places, never in git:

• Locally: a .env file in the worker's directory (gitignored), used by ntn workers exec --local.
• Deployed: worker env vars, managed with the CLI:

cd <worker>
ntn workers env set MY_API_KEY=abc123   # set on the deployed worker
ntn workers env push                    # or push the whole local .env
ntn workers env pull                    # write remote vars into local .env
ntn workers env list

Push secrets before deploying code that needs them.

Conventions

• workers.json is committed. The official scaffold gitignores it, but it only contains IDs (workspace + worker), not secrets. It's what ties each directory to my deployed worker — I commit it so that when I clone this repo on another machine, ntn workers deploy updates the existing worker instead of creating a new one. If you're copying a worker into your own setup, delete it and let your first deploy create your own (see Using these workers yourself).
• One worker per directory, fully self-contained. Duplication between workers is fine; simplicity beats sharing.
• .agents/ holds the official platform guide and skills from the ntn scaffold, shared once at the repo root; .examples/ holds the scaffold's reference example for each capability type. Both are refreshed automatically by new-worker.sh. AGENTS.md (and the CLAUDE.md symlink) document the repo conventions for AI agents — this repo is built to be worked on with Claude Code / Codex.

Reference

• Workers documentation
• Platform guide + capability API (from the official scaffold)
• ntn workers --help