IDAD

Why IDAD?

• Zero to PR asynchronously — From issue to ready-to-merge pull request. No more context switching between planning, coding, testing, and reviewing.
• Self-improving system — After each merge, IDAD analyzes changes and updates itself to work better with your stack.
• Opt-in automation — Automation only runs on issues with the idad:issue-review label. Remove the label to pause. Add comments to redirect.
• Two human gates — You approve the plan before coding starts, then review the final PR before merge. Agents handle the work between gates; you stay in control at decision points.
• GitHub native — Built on GitHub Actions. No external services, no new tools to learn. Works with your existing workflow.
• Configurable agent ensemble — Nine specialized agents, each tuned to its task. Use Opus for complex planning, Haiku for fast implementation if you're using Claude Code. Mix models across vendors if you are using Cursor Agent.

Why do developers love IDAD? Because it's their new favorite DAD — it actually finishes the projects it starts.

How It Works

You create an issue with idad:issue-review label
         ↓
🤖 Issue Review Agent → refines and classifies
         ↓
🤖 Planner Agent → creates implementation plan
         ↓
👤 You review the plan → approve or request changes
         ↓
🤖 Implementer Agent → writes code and tests
         ↓
🔒 Security Scanner → checks for vulnerabilities
         ↓
✅ CI → runs tests
         ↓
🤖 Reviewer Agent → performs code review
         ↓
🤖 Documenter Agent → updates documentation
         ↓
👤 You review and merge the PR
         ↓
🤖 IDAD Agent → analyzes for system improvements

The key insight: humans stay in control at critical points. You approve the plan before coding starts, and you review the final PR before merging.

Install

Add IDAD to any existing repository with one command:

curl -fsSL https://raw.githubusercontent.com/kidrecursive/idad/main/install.sh | bash

The installer will:

• Ask which AI CLI you want to use (Claude Code, Cursor, or Codex)
• Download IDAD agent definitions, rules, and workflow
• Install slash commands for local CLI usage
• Guide you through GitHub App and API key setup
• Configure repository labels and permissions

GitHub App Setup

IDAD requires a GitHub App to enable workflows to trigger other workflows and perform automated actions.

1. Create the GitHub App

Go to GitHub App Settings and configure:

• Name: IDAD Automation (or your preferred name)
• Homepage URL: Your repository URL
• Webhook: Uncheck "Active" (not needed)

Repository permissions required:

2. Generate Private Key & Install

On the app's settings page, generate a private key and save the .pem file. Then install the app on your repository.

3. Add Secrets

# Get your App ID from the app's settings page
gh secret set IDAD_APP_ID

# Add the private key from your .pem file
gh secret set IDAD_APP_PRIVATE_KEY < path/to/private-key.pem

# Add your AI CLI API key (choose based on your CLI)
gh secret set ANTHROPIC_API_KEY     # For Claude Code (API key)
gh secret set ANTHROPIC_AUTH_TOKEN  # For Claude Code (OAuth - alternative)
gh secret set CURSOR_API_KEY        # For Cursor Agent
gh secret set OPENAI_API_KEY        # For OpenAI Codex

Try It

# Create your first automated issue
gh issue create \
  --title "Add hello world feature" \
  --label "idad:issue-review" \
  --body "Create a simple hello world function with tests."

# Watch the agents work
gh run list --workflow=idad.yml --limit 5

Within ~8 minutes, you'll have a ready-to-merge PR with code, tests, and updated documentation.

Agents & Models

The installer configures default models based on your CLI:

Override any agent's model via repository variables:

# Override a specific agent
gh variable set IDAD_MODEL_REVIEWER --body "claude-sonnet-4-5-20250929"

# Override the default for all agents
gh variable set IDAD_MODEL_DEFAULT --body "your-model-name"

Available variables: IDAD_MODEL_DEFAULT, IDAD_MODEL_PLANNER, IDAD_MODEL_IMPLEMENTER, IDAD_MODEL_REVIEWER, IDAD_MODEL_SECURITY, IDAD_MODEL_DOCUMENTER, IDAD_MODEL_ISSUE_REVIEW, IDAD_MODEL_IDAD, IDAD_MODEL_REPORTING

Labels

Add idad:issue-review to any issue to enable automation. Only ONE idad:* label at a time.

Manual Triggers

# Trigger specific agent
gh workflow run idad.yml -f agent="planner" -f issue="123"

# Re-run implementer on existing PR
gh workflow run idad.yml -f agent="implementer" -f issue="123" -f pr="456"

# Trigger security scan
gh workflow run idad.yml -f agent="security-scanner" -f pr="456"

Local Usage

IDAD includes slash commands for local CLI usage:

Note: Codex doesn't support slash commands. Use @.idad/README.md to reference IDAD instead.

Security

• Human Review Gates: Plan approval and PR review required before any code merges
• GitHub App: Scoped to specific repositories only
• Private Key: Stored securely as repository secret
• Installation Tokens: Auto-generated, short-lived (1 hour)
• Security Scanner: Checks for vulnerabilities before review
• Opt-in Only: Automation requires explicit idad:issue-review label
• Bot Identity: All actions clearly attributed to agent emails

Documentation

• Quick Start — Get running in 5 minutes
• Installation — Detailed setup guide
• Workflow Guide — Complete workflow walkthrough
• Agent Reference — All agents documented
• Troubleshooting — Problem solving
• Operations — Maintenance and management