{"id":44852605,"url":"https://github.com/devxoul/vibe-notion","last_synced_at":"2026-04-05T17:03:58.787Z","repository":{"id":338037542,"uuid":"1156133506","full_name":"devxoul/vibe-notion","owner":"devxoul","description":"Notion automation CLI for AI agents","archived":false,"fork":false,"pushed_at":"2026-03-16T15:14:34.000Z","size":8309,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-16T18:59:28.577Z","etag":null,"topics":["notion","vibe-coding"],"latest_commit_sha":null,"homepage":"https://vibevibe.notion.site/README-f192be2ce02b4bc2a6539dd8422ed58f","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devxoul.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-12T09:50:55.000Z","updated_at":"2026-03-16T15:14:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/devxoul/vibe-notion","commit_stats":null,"previous_names":["devxoul/agent-notion","devxoul/vibe-notion"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/devxoul/vibe-notion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devxoul%2Fvibe-notion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devxoul%2Fvibe-notion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devxoul%2Fvibe-notion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devxoul%2Fvibe-notion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devxoul","download_url":"https://codeload.github.com/devxoul/vibe-notion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devxoul%2Fvibe-notion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["notion","vibe-coding"],"created_at":"2026-02-17T06:33:32.483Z","updated_at":"2026-04-01T19:34:27.695Z","avatar_url":"https://github.com/devxoul.png","language":"TypeScript","funding_links":[],"categories":["Knowledge \u0026 Docs"],"sub_categories":[],"readme":"# Vibe Notion\n\n[![npm version](https://img.shields.io/npm/v/vibe-notion)](https://www.npmjs.com/package/vibe-notion) [![SkillPad - vibe-notion](https://img.shields.io/badge/SkillPad-vibe--notion-1a1a1a)](https://skillpad.dev/install/devxoul/vibe-notion/vibe-notion) [![SkillPad - vibe-notionbot](https://img.shields.io/badge/SkillPad-vibe--notionbot-1a1a1a)](https://skillpad.dev/install/devxoul/vibe-notion/vibe-notionbot)\n\n![demo](./docs/public/vibe-notion-demo.gif)\n\n**Give your AI agent the power to read and write Notion pages, databases, and more.**\n\nA full-coverage, agent-friendly CLI for the Notion API. Ships two CLIs — `vibe-notion` for the unofficial private API (act as yourself) and `vibe-notionbot` for the official Integration API (act as a bot).\n\n## Table of Contents\n\n- [Why Vibe Notion?](#why-vibe-notion)\n- [Installation](#installation)\n- [Agent Skills](#agent-skills)\n  - [SkillPad](#skillpad)\n  - [Skills CLI](#skills-cli)\n  - [Claude Code Plugin](#claude-code-plugin)\n  - [OpenCode Plugin](#opencode-plugin)\n- [Quick Start](#quick-start)\n- [Command Overview](#command-overview)\n- [Use Cases](#use-cases)\n  - [Research \u0026 Discovery](#research--discovery)\n  - [Project Tracking](#project-tracking)\n  - [Creating \u0026 Writing](#creating--writing)\n  - [Automation \u0026 Pipelines](#automation--pipelines)\n  - [...and More](#and-more)\n- [Philosophy](#philosophy)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why Vibe Notion?\n\nNotion's official API only supports Integration (bot) tokens — your agent can't do things **on behalf of you**. Vibe Notion solves this by extracting your `token_v2` from the Notion desktop app, so your agent operates as you, with your full permissions.\n\nNeed official API access instead? `vibe-notionbot` is included and fully supports Integration tokens via `NOTION_TOKEN`.\n\n- **Act as you** — `vibe-notion` extracts `token_v2` from the Notion desktop app to operate with your own permissions\n- **Bot support too** — `vibe-notionbot` supports official Integration tokens via `NOTION_TOKEN`\n- **Full API coverage** — Pages, databases, blocks, users, search, comments, and workspaces\n- **Agent friendly** — JSON output by default, perfect for LLM tool use\n- **Agent memory** — Remembers workspace IDs, page names, and preferences across sessions\n- **Token efficient** — CLI, not MCP. Load only what you need. ([Why not MCP?](#philosophy))\n\n## Installation\n\n```bash\nnpm install -g vibe-notion\n```\n\nOr use your favorite package manager.\n\nThis installs both the `vibe-notion` and `vibe-notionbot` CLI tools.\n\n## Agent Skills\n\nVibe Notion includes [Agent Skills](https://agentskills.io/) that teach your AI agent how to use the CLI effectively. Two skills are available:\n\n- **`vibe-notion`** — For the unofficial private API (`token_v2`)\n- **`vibe-notionbot`** — For the official Integration API (`NOTION_TOKEN`)\n\n### SkillPad\n\nSkillPad is a GUI app for Agent Skills. See [skillpad.dev](https://skillpad.dev/) for more details.\n\n[![Available on SkillPad](https://badge.skillpad.dev/vibe-notion/dark.svg)](https://skillpad.dev/install/devxoul/vibe-notion/vibe-notion) [![Available on SkillPad](https://badge.skillpad.dev/vibe-notionbot/dark.svg)](https://skillpad.dev/install/devxoul/vibe-notion/vibe-notionbot)\n\n\n### Skills CLI\n\nSkills CLI is a CLI tool for Agent Skills. See [skills.sh](https://skills.sh/) for more details.\n\n```bash\nnpx skills add devxoul/vibe-notion\n```\n\n### Claude Code Plugin\n\n```\n/plugin marketplace add devxoul/vibe-notion\n/plugin install vibe-notion\n```\n\n### OpenCode Plugin\n\nAdd to your `opencode.jsonc`:\n\n```jsonc\n{\n  \"plugins\": [\n    \"vibe-notion\"\n  ]\n}\n```\n\n## Quick Start\n\n### `vibe-notion` (Private API — act as yourself)\n\n```bash\n# 1. List your workspaces\nvibe-notion workspace list --pretty\n\n# 2. Search for something\nvibe-notion search \"Roadmap\" --workspace-id \u003cworkspace-id\u003e --pretty\n\n# 3. Get page details\nvibe-notion page get \u003cpage-id\u003e --workspace-id \u003cworkspace-id\u003e --pretty\n```\n\n### `vibe-notionbot` (Official API — act as a bot)\n\n```bash\n# 1. Set your Notion Integration Token\nexport NOTION_TOKEN=secret_xxx\n\n# 2. Check auth status\nvibe-notionbot auth status --pretty\n\n# 3. Search for something\nvibe-notionbot search \"Roadmap\" --filter page --pretty\n\n# 4. Get page details\nvibe-notionbot page get \u003cpage-id\u003e --pretty\n```\n\n## Command Overview\n\n### `vibe-notion` (Private API)\n\n| Command | Description |\n|---------|-------------|\n| `auth` | Extract token, check status, logout |\n| `workspace` | List accessible workspaces |\n| `page` | Get, list, create, update, archive pages |\n| `database` | Get schema, query, create, update, delete properties, add/update rows, list, manage views |\n| `block` | Get, list children, append (with nested markdown support), update, delete blocks |\n| `user` | Get current user, get user by ID |\n| `search` | Workspace search |\n| `comment` | List, create, and get comments (including inline block-level comments) |\n\n\u003e All commands that operate within a workspace require `--workspace-id`. Use `vibe-notion workspace list` to find yours.\n\n### `vibe-notionbot` (Official API)\n\n| Command | Description |\n|---------|-------------|\n| `auth` | Check authentication status |\n| `page` | Get, create, update, archive pages, retrieve properties |\n| `database` | Get schema, query, create, update, delete properties, list databases |\n| `block` | Get, list children, append (with nested markdown support), update, delete blocks |\n| `user` | List users, get user info, get bot info |\n| `search` | Global workspace search with filters |\n| `comment` | List, create, and get comments (including inline block-level comments) |\n\n\u003e Requires `NOTION_TOKEN` environment variable with an Integration token from the [Notion Developer Portal](https://www.notion.so/my-integrations).\n\n## Use Cases\n\n### Research \u0026 Discovery\n\nPull context from Notion before you start working — no tab-switching, no skimming.\n\n\u003e \"Gather all context from the BUG-1234 page — read the description, comments, and any linked pages so I can start fixing it.\"\n\n\u003e \"Search our Engineering Wiki for any existing discussion about rate limiting before I write a new proposal.\"\n\n\u003e \"Look up our Onboarding Guide page and answer: what's the process for requesting AWS access?\"\n\n\u003e \"Search across all workspaces for any page mentioning 'API deprecation' so I know if this was discussed before.\"\n\n\u003e \"Read the API Design Principles page and the REST Conventions page, then tell me if our current approach violates any of them.\"\n\n### Project Tracking\n\nLet your agent check, update, and clean up project boards without leaving your editor.\n\n\u003e \"Query the Sprint 24 database and tell me which tasks are still in progress or blocked.\"\n\n\u003e \"Update the status of task INFRA-42 in the Sprint database to Done and set the completed date to today.\"\n\n\u003e \"Find all tasks in the Q1 Roadmap database with status Done and archive them.\"\n\n\u003e \"List everything assigned to me across the Backend and Infrastructure databases that's due this week.\"\n\n\u003e \"Move all P0 bugs from the Triage database to the Sprint 25 database and set their status to To Do.\"\n\n### Creating \u0026 Writing\n\nCreate pages, file reports, and post updates — all from a prompt.\n\n\u003e \"Create a meeting notes page under the Team Meetings database with today's date, attendees, and an empty agenda section.\"\n\n\u003e \"I found a crash in production. Create a bug report page in the Bug Tracker database with this stack trace, set priority to P1, and assign it to me.\"\n\n\u003e \"Post a comment on the Project Alpha page summarizing what the team shipped today.\"\n\n\u003e \"Write an RFC page in the Engineering Proposals database with the title 'Migrate to gRPC' and scaffold the Problem, Proposal, Alternatives, and Open Questions sections.\"\n\n\u003e \"Add a new row to the Interview Scorecard database for the candidate I just talked to, with my notes and a Strong Hire recommendation.\"\n\n### Automation \u0026 Pipelines\n\nWire Notion into your CI, scripts, or agent workflows as a read/write layer.\n\n\u003e \"A new user just signed up. Add a row to the Leads database with their name, email, and source.\"\n\n\u003e \"Append today's deploy results to the Deploy Log page — include the commit hash, status, and timestamp.\"\n\n\u003e \"Read the content of the v2.3 Release page and draft a changelog from it.\"\n\n\u003e \"Every time a GitHub issue is labeled 'needs-design', create a page in the Design Requests database with the issue title, link, and reporter.\"\n\n\u003e \"Query the On-Call Schedule database for this week's rotation and post the name in our Slack channel.\"\n\n### ...and More\n\nThese are just starting points. Your agent has full read/write access to Notion — the real limit is your creativity. If you build something amazing with Vibe Notion, [let me know](https://x.com/devxoul)!\n## Philosophy\n\n**Why not MCP?** MCP servers expose all tools at once, bloating context and confusing agents. **[Agent Skills](https://agentskills.io/) + agent-friendly CLI** offer a better approach—load what you need, when you need it. Fewer tokens, cleaner context, better output.\n\nInspired by [agent-browser](https://github.com/vercel-labs/agent-browser) from Vercel Labs and [agent-messenger](https://github.com/devxoul/agent-messenger).\n\n## Contributing\n\n```bash\nbun install    # Install dependencies\nbun link       # Link CLI globally for local testing\nbun test       # Run tests\nbun run lint   # Lint\nbun run build  # Build\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevxoul%2Fvibe-notion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevxoul%2Fvibe-notion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevxoul%2Fvibe-notion/lists"}