@overseedai/notion-ops

Token-lean access to Overseed's Notion for agents and humans, backed by the ntn CLI. Ships the nops command.

This is intentionally specific to Overseed's Notion workspace. It is not trying to become a general Notion client; ntn already does that. The problem this repo solves is narrower: agents should use named Overseed surfaces, cached board schemas, and compact targeted queries instead of workspace-wide search, giant JSON dumps, or guessed property names.

UX stance

The product surface is the agent workflow, not a broad Notion abstraction. A good nops interaction should help an agent answer: which Overseed surface should I use, what fields are safe to query, what compact refs can I reuse, and when do I need to refresh schema or stop for auth? New CLI features should earn their keep by removing repeated agent failure modes in those flows.

Onboard a new machine

# 1. install the CLI
bun add -g @overseedai/notion-ops

# 2. create/refresh local config and verify ntn auth/workspace
nops init
nops doctor

# 3. install the skill into your coding agent of choice
nops skill install claude
# or: codex | gemini | opencode | cursor | agents

If nops doctor reports a missing ntn login or workspace, run ntn login and then rerun nops doctor. Package updates carry the Overseed default registry automatically; local config is only for machine-specific additions and refreshed schemas.

Age gate: the global bunfig enforces a 7-day minimumReleaseAge. First-party packages are excluded (@overseedai/* in minimumReleaseAgeExcludes) so a fresh publish installs immediately.

Architecture

• Code + defaults ship via npm; the default registry/schema are read from the installed package on every run.
• Local state lives in ~/.config/notion-ops/ (registry.local.json + schema.cache.local.json + page.aliases.json). Override the location with NOPS_HOME.
• Agent artifacts are authored files under agents/ — one folder per agent. nops skill install places them.
• The canonical skill is SKILL.md; the agent-specific files are install wrappers/adaptations for current agent surfaces.

bin/nops.ts                       the CLI
config/registry.seed.json         default surface map
config/schema.cache.seed.json     default schema cache
~/.config/notion-ops/registry.local.json       local additions/overrides
~/.config/notion-ops/schema.cache.local.json   refreshed local schemas
~/.config/notion-ops/page.aliases.json         compact IDs from recent listings
SKILL.md                          canonical skill instructions
agents/<agent>/...                per-agent skill/instruction artifacts

Quick start

nops ls
nops version
nops update
nops doctor
nops help tickets
nops surface add vendor-board <data-source-id> --purpose "Vendor tasks"
nops tickets eng-board --status "In progress" \
  --where Priority=High --props Priority,Tags
nops todo eng-board "Fix onboarding bug" --priority High --type Bug
nops page append <listed-id> "Finding: ..."
nops refs eng-board
nops mem ls

For richer agent guidance, install the skill and let the agent follow the workflow cookbook in SKILL.md.

Verbs

| verb | what | | --- | --- | | nops ls | list registered surfaces | | nops schema [name] | list cached schema summaries or show one data source schema | | nops tickets <name> [--status S] [--where Property=Value] [--props P[,P]] [--limit N] [--json] | query a board, compact output | | nops create <surface> "<title>" [--status S] [--set Property=Value] [--body markdown] | create a page/ticket in a data source | | nops todo <surface> "<title>" [--priority P] [--due YYYY-MM-DD] [--type value] | create a todo ticket with a default status | | nops get <page-surface\|page-id\|listed-id> [--json] | page body as Markdown; accepts listed short IDs | | nops page update <id> --content markdown | replace a page body by listed ID or full page ID | | nops page append <id> "markdown" | append a dated note to a page by listed ID or full page ID | | nops refs [surface] [--json] | list cached compact page refs from recent listings | | nops refs clear [surface] | clear stale cached compact page refs | | nops mem [ls\|get\|append] | read/append long-term memory; accepts listed short IDs | | nops refresh [name] | rebuild schema cache | | nops init [--force] | create/migrate local config; --force resets local overrides/cache/aliases | | nops doctor | show package, update, config, and ntn health | | nops version / nops --version | print installed package version | | nops update / nops upgrade | update the global CLI, then print verification commands | | nops surface add <name> <id> [--type data_source\|page] [--purpose text] | add a local surface | | nops surface rm <name> | remove a local surface or override | | nops skill install <agent> | install the skill into a coding agent | | nops help [command] | show global or command-specific help with examples |

Compact bracketed IDs from nops tickets and nops mem ls can be reused with nops get, nops mem get, and nops mem append. Use nops refs to inspect the current reusable ID cache. Use nops refs clear [surface] to clear stale short IDs without resetting local surfaces or refreshed schemas. nops ls shows whether each surface comes from package defaults, local config, or a local override. Use --where Property=Value for schema-aware filters such as --where Priority=High or --where Tags=Bug; repeat it to combine filters. Use --props Priority,Tags to include selected fields in compact output without dumping raw JSON. Use nops todo for quick Engineering Board or personal task capture. Use nops create for notes, project updates, and other schema-aware data-source page creation. Use nops page append for dated roadmap notes/findings, and nops page update only after fetching and editing the full Markdown body. Run bare nops schema to see which cached schemas exist and when they were fetched.

Installing the skill into agents

nops skill install <agent> (user-global by default; --project for the current repo, --path FILE to override). Source artifacts live in agents/<agent>/.

| agent | target | | --- | --- | | claude | symlinked skill in ~/.claude/skills/notion-ops | | codex | managed block in ~/.codex/AGENTS.md | | gemini | managed block in ~/.gemini/GEMINI.md | | opencode | managed block in ~/.config/opencode/AGENTS.md | | cursor | rule file .cursor/rules/notion-ops.mdc | | agents | managed block in any AGENTS.md (use --path) |

Markdown agents get a small idempotent block (re-running won't duplicate it; nops skill uninstall <agent> removes it cleanly). nops skill list shows all.

For unsupported agents, print a copy/paste handoff prompt. Give that prompt to the other agent so it can create or adapt its own native skill/instructions:

nops skill guide

Adding a surface

For a machine-local surface:

nops surface add vendor-board <data-source-id> --purpose "Vendor tasks"
nops refresh vendor-board

Use --type page for a page surface. nops surface rm <name> removes a local surface or local override. To ship a surface team-wide, edit config/registry.seed.json and release the package.

Local development

bun run bin/nops.ts ls            # runs from a bare clone, no install
bun install                       # only adds bun-types for editor types
nops skill install claude         # in a clone, sources from ./agents

Releasing

CI publishes via npm Trusted Publishing (OIDC) — no NPM_TOKEN, no OTP. One command cuts a release; the tag triggers .github/workflows/publish.yml:

bun run release patch        # or: minor | major | X.Y.Z

The workflow re-checks the tag matches package.json before publishing. Add the release to the ## Unreleased section of CHANGELOG.md first and it gets dated automatically.

First publish (one time)

OIDC can't create a package — and the npm web UI only attaches existing packages to teams. So claim @overseedai/notion-ops with a manual publish from the CLI; this creates the org package:

cd ~/projects/notion-ops && npm publish --otp=<code>
# If npm returns 402, publish public:
npm publish --access public --otp=<code>

Enable token-free CI (one time, after the package exists)

On npmjs.com → the package → Settings → Trusted Publisher → GitHub Actions:

| field | value | | --- | --- | | Organization or user | OverseedAI | | Repository name | notion-ops | | Workflow filename | publish.yml | | Environment name | (blank) | | Allowed actions | npm publish |

Then every bun run release publishes via OIDC. No secret needed — delete any NPM_TOKEN you set, and optionally set the account to disallow tokens for max security.

Notes

• NOTION_API_TOKEN lives in the ntn keychain or your env — never committed.
• The schema cache can drift if someone edits a board; nops refresh <name> re-syncs. Verbs fail loudly on a missing cached property rather than guessing.