Notion Setup

Configure Notion databases for Claudear

Notion Setup

Claudear integrates with Notion using a polling-based approach. This guide covers setting up Notion databases to work with Claudear.

How Notion Integration Works

Unlike Linear (which uses webhooks), Notion integration uses polling:

1. Claudear polls your database every N seconds (default: 5)
2. Detects pages that moved to "Todo" status
3. Picks up new tasks and starts Claude Code
4. Updates page properties as work progresses

Advantages:

• No ngrok or public URL needed
• Simpler setup
• Works behind firewalls

1. Create a Notion Integration

1. Go to Notion Integrations
2. Click New integration
3. Configure:
   • Name: Claudear
   • Associated workspace: Your workspace
   • Capabilities: Read content, Update content, Insert content
4. Click Submit
5. Copy the Internal Integration Token (starts with secret_)

2. Share Database with Integration

For each database you want Claudear to manage:

1. Open the database in Notion
2. Click ... in the top right
3. Click Add connections
4. Search for and select "Claudear"

3. Get Database ID

The database ID is in the URL when viewing the database:

https://notion.so/workspace/abc123def456?v=...
                          ↑
                    Database ID

Tips:

• The ID is the 32-character string before ?v=
• It may contain hyphens (which are removed in env var names)

4. Configure Database Properties

Claudear uses these properties on your Notion database:

Required Property

Auto-Created Properties

Claudear automatically creates these properties if they don't exist:

5. Configure Status Values

Claudear auto-detects common status names:

For custom status names, use per-database environment variables:

# Replace ABC123 with your database ID (uppercase, no hyphens)
NOTION_ABC123_STATUS_TODO=Next Up
NOTION_ABC123_STATUS_IN_PROGRESS=Working
NOTION_ABC123_STATUS_IN_REVIEW=Review
NOTION_ABC123_STATUS_DONE=Shipped

6. Environment Configuration

Single Database

NOTION_API_KEY=secret_xxxxxxxxxxxxx
NOTION_DATABASE_ID=abc123def456
NOTION_POLL_INTERVAL=5

REPO_PATH=/path/to/your/repo
GITHUB_TOKEN=ghp_xxxxx

Multiple Databases

NOTION_API_KEY=secret_xxxxxxxxxxxxx
NOTION_DATABASE_IDS=abc123,def456,ghi789
NOTION_POLL_INTERVAL=5

# Per-database repository paths
NOTION_ABC123_REPO=/path/to/project-alpha-repo
NOTION_DEF456_REPO=/path/to/project-beta-repo
NOTION_GHI789_REPO=/path/to/project-gamma-repo

GITHUB_TOKEN=ghp_xxxxx

Polling Configuration

Recommendations:

• 5 seconds: Good for active development
• 15-30 seconds: Lower API usage for many databases
• 60+ seconds: Minimal polling for low-priority databases

Troubleshooting

Tasks Not Being Picked Up

1. Verify integration access:

   • Open database → ... → Add connections → Check Claudear is listed

2. Check status value matches:

   • Claudear auto-detects common names (Todo, In Progress, Done)
   • For custom names, use NOTION_{DB}_STATUS_TODO=YourStatus

3. Verify database ID:

   • Check URL carefully
   • Try both with and without hyphens

"Unauthorized" Errors

1. Check API key is valid:

   • Regenerate if needed at notion.so/my-integrations

2. Verify database is shared:

   • Each database must explicitly add the integration

Properties Not Appearing

Claudear creates properties on first task pickup. If they're not appearing:

1. Trigger a task by moving a page to "Todo"
2. Check Claudear logs for errors
3. Verify integration has "Update content" capability

Rate Limiting

If you see rate limit errors:

1. Increase poll interval:

   NOTION_POLL_INTERVAL=30
   

2. Reduce concurrent databases

3. Check Notion API status: status.notion.so

Best Practices

Database Structure

• Use Status property (not Select) for better UI
• Keep page titles concise - they become PR titles
• Use description for context - Claude reads page content

Task Descriptions

Good task descriptions help Claude succeed:

## Goal
Add a dark mode toggle to the settings page

## Acceptance Criteria
- Toggle appears in Settings
- Persists preference in localStorage
- Uses system preference as default

## Technical Notes
- Use existing ThemeContext
- Follow color token pattern in theme.ts

Monitoring

• Check "Current Status" property for real-time updates
• "Blocked" checkbox indicates Claude needs help
• Comments appear on the page when Claude asks questions