notion-vibe (beta)

Overview

notion-vibe is a headless orchestrator for running parallel coding agents that attaches to your existing kanban.

It currently supports:

• Notion as the kanban system
• Codex as the coding agent

The goal is to offer engineers a flexible, AI-powered tool for product management.

Features

• Headless tool that attaches to your existing Notion kanban.
• Run parallel tasks with configurable concurrency.
• Agent execution happens in isolated git worktrees per task.
• Automatic branch, commit, push, and GitHub PR creation.
• Automatic Notion card update.
• Dry-run mode for validating polling/planning flow without write side effects.

Installation

npx notion-vibe

Minimum requirements:

• Node.js 18+
• A git repository with an origin remote
• gh authenticated for PR creation (gh auth login)
• A Notion database with:
  • Status (status property)
  • PR (URL property)

Configure environment variables (.env file):

NOTION_TOKEN="..."
NOTION_DB_ID="..."
NOTION_DATA_SOURCE_ID="..." # required when the database has multiple data sources

Helpful optional flags:

npx notion-vibe --project-dir /path/to/your/project --dry-run true

Support

• Open an issue in this repository for bugs and feature requests.
• Include your command, environment variables used, and logs when reporting issues.

Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a branch for your change.
3. Add or update tests.
4. Run lint, typecheck, and tests.
5. Open a pull request with a clear summary and verification steps.

This project uses Conventional Commits; make sure your commits respect that.

Development

Clone and install:

git clone <repo-url>
cd notion-vibe
npm install

Common commands:

npm run build
npm start -- --project-dir /path/to/your/project
npm test
npm run test:watch
npm run typecheck
npm run lint

Use dry run to validate orchestration flow without write side effects. Dry run still reads Notion task content, but it does not create worktrees, run agents, commit/push branches, create PRs, or update Notion pages:

npm start -- --dry-run true