t3ta/coduck

npm install

ORCHESTRATOR_PORT=3000
ORCHESTRATOR_URL=http://localhost:3000
WORKER_POLL_INTERVAL_MS=5000
WORKTREE_BASE_DIR=./worktrees
CODEX_CLI_PATH=codex
GIT_PATH=git
WORKER_CONCURRENCY=3

# Terminal 1: build once (optional but recommended for MCP server)
npm run build

# Terminal 2: start Orchestrator
npm run orchestrator

# Terminal 3: start Worker
npm run worker

# Increase parallel workers (example: 5)
WORKER_CONCURRENCY=5 npm run worker

# Optionally manage long-running processes with pm2 or a similar process manager

# Only for testing
npm run mcp

npm run build

{
  "projects": {
    "/home/user/workspace/coduck": {
      "mcpServers": {
        "coduck-orchestrator": {
          "type": "stdio",
          "command": "node",
          "args": ["/home/user/workspace/coduck/dist/mcp.js"],
          "env": {
            "ORCHESTRATOR_URL": "http://localhost:3000"
          }
        }
      }
    }
  }
}

{
  "projects": {
    "/home/user/workspace/my-app": {
      "mcpServers": {
        "coduck-orchestrator": {
          "type": "stdio",
          "command": "node",
          "args": ["/home/user/workspace/coduck/dist/mcp.js"],
          "env": {
            "ORCHESTRATOR_URL": "http://localhost:3000",
            "WORKTREE_BASE_DIR": "/home/user/workspace/my-app/.coduck/worktrees"
          },
          "cwd": "/home/user/workspace/my-app"
        }
      }
    },
    "/home/user/workspace/another-project": {
      "mcpServers": {
        "coduck-orchestrator": {
          "type": "stdio",
          "command": "node",
          "args": ["/home/user/workspace/coduck/dist/mcp.js"],
          "env": {
            "ORCHESTRATOR_URL": "http://localhost:3000",
            "WORKTREE_BASE_DIR": "/home/user/workspace/another-project/.coduck/worktrees"
          },
          "cwd": "/home/user/workspace/another-project"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "coduck-orchestrator": {
      "type": "stdio",
      "command": "node",
      "args": ["/home/user/workspace/coduck/dist/mcp.js"],
      "env": {
        "ORCHESTRATOR_URL": "http://localhost:3000"
      }
    }
  }
}

# Dry run - show what would be removed
npm run cleanup -- --dry-run --all

# Clean up completed jobs (done, failed, cancelled)
npm run cleanup -- --jobs

# Clean up jobs with specific status
npm run cleanup -- --jobs --status=done,failed

# Clean up jobs older than 7 days
npm run cleanup -- --jobs --max-age=7

# Clean up orphaned worktrees
npm run cleanup -- --worktrees

# Clean up unused repository cache
npm run cleanup -- --repo-cache

# Clean up everything
npm run cleanup -- --all

// Delete a single job
delete_job({ id: "job-id" })

// Cleanup failed jobs
cleanup_jobs({ statuses: ["failed"] })

// Cleanup jobs older than 7 days
cleanup_jobs({ statuses: ["done", "failed"], maxAgeDays: 7 })

# Delete a single job
curl -X DELETE http://localhost:3000/jobs/{job-id}

# Cleanup failed jobs
curl -X POST http://localhost:3000/jobs/cleanup \
  -H "Content-Type: application/json" \
  -d '{"statuses": ["failed"]}'

// Traditional workflow with auto-push
enqueue_codex_job({
  goal: "Add TypeScript strict mode",
  context_files: ["tsconfig.json"],
  base_ref: "main"
})

// Worker automatically:
// 1. Creates worktree with auto-generated branch (e.g., codex/add-typescript-lm3k9-a1b2c3d4)
// 2. Runs Codex
// 3. Commits and pushes changes
// 4. Updates job status

// Continue conversation if needed
continue_codex_job({
  id: "job-id",
  prompt: "Also enable noImplicitAny"
})

// Feature: Comment system with backend and frontend jobs
enqueue_codex_job({
  goal: "Implement comment API endpoints",
  context_files: ["src/api/comments.ts"],
  branch_name: "feature/comment-system",
  push_mode: "never",
  feature_id: "comment-system",
  feature_part: "backend"
})

enqueue_codex_job({
  goal: "Add comment UI components",
  context_files: ["src/components/Comment.tsx"],
  branch_name: "feature/comment-system",
  push_mode: "never",
  feature_id: "comment-system",
  feature_part: "frontend"
})

// Worker executes both jobs:
// 1. Shares the same worktree (feature/comment-system)
// 2. Each job commits changes to the same branch
// 3. No automatic push (push_mode: "never")

// Review locally, then push and create PR manually:
// cd worktrees/feature-comment-system
// git push -u origin feature/comment-system
// gh pr create

// Auto-generates branch as feature/<feature_id>
enqueue_codex_job({
  goal: "Add user authentication",
  context_files: ["src/auth/"],
  feature_id: "user-auth",
  push_mode: "never"
})

// Creates branch: feature/user-auth
// Commits locally without pushing

npm run build

npm run typecheck