Documentation

Get from zero to your first AI-generated pull request in under 5 minutes.

Prerequisites

Install & initialize

npm install -g ticket-to-pr
npx ticket-to-pr init

Three steps to your first PR

1. Create a Notion integration

Go to notion.so/my-integrations and create a new internal integration. Give it a name like “TicketToPR” and copy the token.

2. Create your database

Create a new database (or use an existing one) with these 16 properties:

3. Configure status columns

Set up 9 status options in order. The daemon uses these names exactly:

4. Connect the integration

Open your database page in Notion, click … in the top-right corner, then Connections, and add the integration you created in step 1.

The init wizard walks you through setup interactively. Here’s what each step looks like:

$ npx ticket-to-pr init
╔═══════════════════════════════════════╗
  ║       TicketToPR — Setup Wizard       ║
  ╚═══════════════════════════════════════╝

  Let's get you set up. This takes about 2 minutes.

? Notion integration token: ntn_**********************
  ✓ Token validated — workspace: "My Workspace"

? Paste your Notion database URL: https://notion.so/abc123...
  ✓ Database connected — "Engineering Backlog"
  ✓ Found 16/16 required properties

Checking prerequisites...
  ✓ Node.js    v22.12.0
  ✓ Git        v2.43.0
  ✓ Claude CLI  v1.0.18
  ✓ GitHub CLI  v2.62.0
  ✓ All tools ready

? Project path: /Users/you/projects/my-app
  ? Build command (npm run build):                  ← auto-detected
  ? Base branch (main): develop
  ? Blocked file patterns: **/migrations/**, **/*.sql
  ? Skip automatic PR creation? (N):
  ? Enable dev access (run scripts, query DB, hit endpoints)? (N): Y
  ? Env file to load (.env.local):                   ← auto-detected
  Detected: TypeScript, Next.js, Tailwind CSS       ← auto-detected
  ? Generate starter CLAUDE.md? (Y):
  ✓ Generated CLAUDE.md
  ✓ Saved to projects.json

  🎉 Setup complete! Run: ticket-to-pr --once

What gets saved

Every ticket flows through a 9-column pipeline. You control when it moves forward.

TicketToPR uses two specialized Claude agents, each with a distinct role, model, and budget.

Environment variables

projects.json

{
  "projects": {
    "my-app": {
      "directory": "/Users/you/projects/my-app",
      "buildCommand": "npm run build",
      "baseBranch": "develop",
      "blockedFiles": ["**/migrations/**", "prisma/schema.prisma", "**/*.sql"],
      "skipPR": false,
      "devAccess": true,
      "envFile": ".env.local"
    }
  }
}

Config constants

CLAUDE.md best practices

The execute agent reads your project’s CLAUDE.md before writing any code. A good CLAUDE.md helps the agent follow your conventions:

# CLAUDE.md

## Project overview
Next.js 14 app with App Router, TypeScript, Tailwind CSS, Prisma ORM.

## Build & test
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Code style
- Use functional components with TypeScript
- Prefer server components; add "use client" only when needed
- Use cn() utility for conditional classes
- All new features need tests

## File structure
- app/ — routes and layouts
- components/ — React components
- lib/ — utilities and shared logic
- prisma/ — database schema

TicketToPR uses the Claude API. You pay Anthropic directly — no markup, no subscription. Here’s what tickets typically cost:

Budget limits

Each agent has a per-ticket budget cap. If the agent reaches the limit, it stops and the ticket moves to Failed. You can change these in config.ts:

Cost visibility

After each run, the actual Claude API cost is written back to the ticket’s Cost property in Notion, so you can track spend per ticket and per project.

Common errors

Recovery

When a ticket fails, the error reason is written to the ticket in Notion. To retry:

1. Read the error on the ticket
2. Fix the underlying issue (e.g. broken build, missing dependency)
3. Drag the ticket back to Review or Execute
4. The daemon will pick it up on the next poll cycle

One-off run

Process all pending tickets once and exit:

ticket-to-pr --once

Continuous mode

Poll Notion every 30 seconds and process tickets as they appear:

ticket-to-pr

macOS LaunchAgent

To run the daemon automatically on login, create a LaunchAgent plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.tickettopr.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>ticket-to-pr</string>
  </array>
  <key>WorkingDirectory</key>
  <string>/Users/you</string>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/tickettopr.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/tickettopr.err</string>
</dict>
</plist>

Then load it:

launchctl load ~/Library/LaunchAgents/com.tickettopr.daemon.plist

Graceful shutdown

Press Ctrl+C to stop. The daemon finishes any in-progress agent work before exiting — it won’t leave orphaned branches or half-written PRs.