Turn your GitHub backlog into pull requests, overnight.

Autoissue is a parallel AI code execution engine that transforms GitHub issues into production-ready pull requests. It intelligently classifies tasks by domain, schedules them for parallel execution, and runs each in an isolated git worktree to prevent conflicts.

• ⚡ 10x Faster - Direct GitHub API via Octokit (no shell overhead)
• 🔄 Parallel Execution - Run up to 10 tasks concurrently with smart scheduling
• 🎯 Domain-Aware - Backend + Frontend run together, Backend + Backend don't
• 🔒 Isolated Worktrees - Each task gets its own directory and branch (zero conflicts)
• 🤖 Automatic PRs - Creates pull requests with issue links and descriptions
• 💰 Budget Tracking - Proactive budget enforcement (checks BEFORE execution)
• 🛡️ Circuit Breakers - Prevents cascading failures with automatic recovery
• 📊 Real-Time Dashboard - Monitor progress, costs, and metrics via web UI
• 🔐 Secure - Optional authentication for dashboard (Basic Auth + Token)
• 📝 Structured Logging - JSON logs with daily rotation for production

npm install -g @venin/autoissue

Or run directly with npx:

npx @venin/autoissue exec autoissue-1

Label your GitHub issues with autoissue-1, then run:

autoissue exec autoissue-1

Autoissue will:

1. Fetch all open issues labeled autoissue-1
2. Classify each by domain (backend, frontend, database, etc.)
3. Check budget before execution
4. Schedule compatible tasks in parallel (3 concurrent by default)
5. Execute each in an isolated git worktree with circuit breaker protection
6. Create pull requests for completed tasks
7. Track costs and provide detailed summary

autoissue exec <label> [options]

Process all GitHub issues with the specified label.

Examples:

# Execute all issues labeled 'autoissue-1'
autoissue exec autoissue-1

# Execute with dashboard enabled
autoissue exec autoissue-1 --dashboard

# Execute with custom config
autoissue exec autoissue-1 --config ./my-config.json

autoissue plan "<directive>" [options]

Use AI to decompose a high-level directive into GitHub issues, then execute them.

Examples:

# Plan and execute
autoissue plan "Build user authentication system"

# Dry-run (show plan without executing)
autoissue plan "Add rate limiting to API" --dry-run

# Execute with custom config
autoissue plan "Implement caching layer" --config ./config.json

autoissue resume [session-id] [options]

Resume a previously interrupted session.

Examples:

# Resume most recent session
autoissue resume

# Resume specific session
autoissue resume abc123xyz

# Resume with dashboard
autoissue resume --dashboard

autoissue status

Display status of recent execution sessions.

autoissue metrics

Display aggregated metrics across all sessions (total cost, success rate, code impact).

Create autoissue.config.json in your project root:

{
  "project": {
    "repo": "owner/repo-name",
    "path": "/path/to/project",
    "baseBranch": "main"
  },
  "executor": {
    "maxParallel": 3,
    "timeoutMinutes": 30,
    "createPr": true,
    "prDraft": false
  },
  "agent": {
    "model": "sonnet",
    "maxBudgetUsd": 5.0,
    "yolo": true
  },
  "maxTotalBudgetUsd": 50.0,
  "dashboard": {
    "enabled": true,
    "port": 3030,
    "auth": {
      "enabled": false
    }
  },
  "planner": {
    "enabled": true,
    "model": "sonnet",
    "maxBudgetUsd": 2.0
  }
}

See autoissue.config.example.json for a complete example with authentication.

Enable the real-time dashboard to monitor execution:

autoissue exec autoissue-1 --dashboard

Then open http://localhost:3030 in your browser to see:

• Running, completed, and failed tasks
• Real-time cost tracking
• Task status with PR links
• Budget remaining

The dashboard exposes REST API endpoints:

# Get all metrics
curl http://localhost:3030/api/metrics

# Get budget state
curl http://localhost:3030/api/metrics/budget

# Get circuit breaker state
curl http://localhost:3030/api/metrics/circuit-breaker

# Reset circuit breaker (requires auth if enabled)
curl -X POST http://localhost:3030/api/circuit-breaker/reset

See server/API.md for complete API documentation.

For production deployments, enable authentication:

{
  "dashboard": {
    "enabled": true,
    "port": 3030,
    "auth": {
      "enabled": true,
      "type": "both",
      "username": "admin",
      "password": "your-secure-password",
      "token": "your-secure-token"
    }
  }
}

Then access the API with credentials:

# Basic auth
curl -u admin:password http://localhost:3030/api/metrics

# Token auth
curl -H "Authorization: Bearer your-token" http://localhost:3030/api/metrics

Autoissue automatically classifies issues by domain for intelligent parallel scheduling:

1. Title Tags - [Backend] Fix login bug → backend
2. Domain Labels - backend, frontend, database, etc.
3. File Paths - Inferred from issue body mentions
4. Keywords - "API endpoint", "UI component", "SQL query"

• backend - APIs, services, business logic
• frontend - UI components, pages, styling
• database - Schemas, migrations, queries
• infrastructure - DevOps, CI/CD, deployment
• security - Auth, permissions, vulnerabilities
• testing - Test suites, fixtures
• documentation - Docs, comments, guides
• unknown - Unclassified (runs sequentially)

• Different domains run in parallel
• Same domain runs sequentially (prevents file conflicts)
• Conflict detection for explicit file mentions

Autoissue 2.0 enforces budgets BEFORE task execution:

1. Estimation - Uses P90 of historical costs, or maxBudgetUsd if no history
2. Pre-check - Validates budget BEFORE spawning agent
3. Tracking - Records actual costs after execution
4. Enforcement - Throws BudgetExceededError if limit reached

{
  "agent": {
    "maxBudgetUsd": 5.0  // Per-task budget
  },
  "maxTotalBudgetUsd": 50.0  // Session budget
}

# Set budget via environment variable
export AUTOISSUE_MAX_BUDGET=25.00
autoissue exec autoissue-1

If estimated cost exceeds budget, execution stops immediately:

❌ Error: Cannot afford 10 tasks: estimated $60.00 exceeds budget $25.00

Use AI to decompose high-level directives into actionable GitHub issues:

autoissue plan "Build user authentication system with JWT and refresh tokens"

The planner will:

1. Analyze the directive
2. Generate GitHub issues with:
   • Detailed descriptions
   • Domain labels
   • Complexity estimates
   • Dependency relationships
3. Create issues in your repo
4. Execute them in dependency order

Preview the plan without creating issues:

autoissue plan "Add Redis caching layer" --dry-run

Autoissue uses circuit breakers to prevent cascading failures:

• Closed - Normal operation
• Open - Fails fast after 5 consecutive failures
• Half-Open - Testing recovery after 60s

Reset manually via API:

curl -X POST http://localhost:3030/api/circuit-breaker/reset

Failed tasks automatically retry with:

• Exponential backoff (1s → 2s → 4s)
• Error classification (retryable vs. non-retryable)
• Circuit breaker integration
• Max 2 retries per task

• validation - Input validation (non-retryable)
• rate_limit - API rate limit (retryable)
• timeout - Operation timeout (retryable)
• crash - Agent crash (retryable)
• network - Network issue (retryable)

autoissue/
├── core/
│   ├── executor.ts          # Main execution loop
│   ├── scheduler.ts          # Sliding window scheduler
│   ├── agent.ts              # Claude agent interface
│   ├── worktree.ts           # Git worktree management
│   ├── planner.ts            # Directive decomposition
│   ├── budget-tracker.ts     # Budget enforcement
│   ├── error-boundaries.ts   # Error handling & circuit breaker
│   └── pr-manager.ts         # Pull request creation
├── lib/
│   ├── github-api.ts         # GitHub API client (Octokit)
│   ├── github-client.ts      # Legacy GitHub client
│   ├── domain-classifier.ts  # Domain classification
│   ├── conflict-detector.ts  # File conflict detection
│   ├── model-selector.ts     # AI model selection
│   └── types.ts              # TypeScript types
├── server/
│   ├── dashboard.ts          # Real-time dashboard server
│   └── API.md                # API documentation
├── ui/
│   └── cli-ui.tsx            # Terminal UI (React Ink)
└── __tests__/
    ├── e2e/                  # End-to-end tests
    └── *.test.ts             # Unit tests

# Run all tests
npm test

# Run specific test suite
npm test -- budget-tracker

# Run with coverage
npm test -- --coverage

# E2E tests (partial - some require real GitHub)
npm test -- e2e

On a typical workload (10 issues, mixed domains):

GitHub API calls:    85ms (vs 850ms in v1.x)
Conflict detection:  12ms (vs 40ms in v1.x)
Budget validation:   <1ms (vs N/A in v1.x)
Total overhead:      ~100ms (vs ~900ms in v1.x)

If you see "Cannot afford X tasks" right away:

# Increase total budget
autoissue exec label --config config.json
# config.json: { "maxTotalBudgetUsd": 100.0 }

# Or reduce per-task budget (better estimates)
# config.json: { "agent": { "maxBudgetUsd": 3.0 } }

If all tasks fail immediately:

# Check circuit breaker state
curl http://localhost:3030/api/metrics/circuit-breaker

# Reset if needed
curl -X POST http://localhost:3030/api/circuit-breaker/reset

If you see "worktree already exists":

# Clean up stale worktrees
git worktree prune

# Remove specific worktree
git worktree remove .worktrees/autoissue-issue-123

# Verify health endpoint works (no auth required)
curl http://localhost:3030/api/health

# Check auth configuration
curl -u username:password http://localhost:3030/api/metrics

• API Reference - Complete REST API documentation
• COMPLETION_PLAN.md - Development roadmap and progress
• autoissue.config.example.json - Example configuration

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

MIT License - see LICENSE for details.

• Built with Claude Code
• Powered by Anthropic Claude API
• GitHub API via @octokit/rest
• Terminal UI with React Ink

Made with ⚡ by Venin Client Systems