Quick Start

Get Clotion running in under 5 minutes

Quick Start

Get Clotion running in under 5 minutes with this quick setup guide.

1. Clone and Install

# 1. Clone the repository
git clone https://github.com/ianborders/clotion.git
cd clotion

# 2. Install the clotion command
pip install clotion

# 3. Create your config
cp .env.example .env

Updating

To update to the latest version:

pip install -U clotion

2. Set Up Notion Integration

Create an Integration

1. Go to notion.so/my-integrations
2. Click + New integration
3. Give it a name like "Clotion"
4. Select your workspace
5. Under Capabilities, enable: Read, Update, Insert content
6. Copy the Internal Integration Token (starts with secret_ or ntn_)

Share Your Database

1. Open your Notion database (the one you'll use for tasks)
2. Click the ... menu in the top right
3. Click Add connections
4. Search for and select your "Clotion" integration

Find Your Database ID

The database ID is in the URL when viewing your database as a full page:

https://notion.so/workspace/abc123def456789012345678901234?v=...
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                           This is your database ID (32 chars)

Tip: If your database is inline on a page, click ... → Open as full page first.

3. Set Up Your Database Status

Your database needs a Status property with these options (case-sensitive):

Important: Status names must match exactly. ToDo is not the same as Todo or To Do.

4. Configure

Edit .env with your values:

# Required
NOTION_API_KEY=secret_xxxxxxxxxxxxx
NOTION_DATABASE_ID=abc123def456789012345678901234
REPO_PATH=/path/to/your/repo

# Status Values (must match your Notion Status property exactly)
NOTION_STATUS_BACKLOG=Backlog
NOTION_STATUS_TODO=ToDo
NOTION_STATUS_IN_PROGRESS=In Progress
NOTION_STATUS_IN_REVIEW=In Review
NOTION_STATUS_DONE=Done

5. Start Clotion

Run from the cloned repository directory:

cd clotion
clotion

Important: Always run clotion from the cloned repository directory. Configuration is loaded from .env in the current working directory.

Clotion will:

1. Connect to your Notion database
2. Auto-create required properties (Blocked, Current Status, Clotion ID, Branch, PR URL)
3. Start polling for task changes
4. Begin listening for cards moved to ToDo

6. Test It

1. Go to your Notion database
2. Create a card in Backlog with a task description
3. Move the card to ToDo
4. Watch Clotion pick up the task!

You'll see output in your terminal as Claude Code:

• Creates a worktree for the task
• Analyzes the requirements
• Implements the solution
• Creates a PR

Next Steps

• Configuration - Full environment variable reference
• How It Works - Understand the task lifecycle
• Notion Setup - Detailed database configuration