Autocode-dev

AI coder agent workflow - Automated code generation that creates pull requests based on Jira work items using Cursor Cloud Agents API.

Overview

Autocode-dev reads Jira issue details and uses Cursor's Cloud Agents API to generate code that implements the requested feature or fix. Cursor automatically creates a pull request with the generated code.

Installation

As npm package (recommended)

npm install autocode-dev
# or
yarn add autocode-dev

From source

git clone https://github.com/Project-Clio/autocode-dev.git
cd autocode-dev
npm install
npm run build

Features

• 🔍 Jira Integration: Fetches issue details from Jira API
• 🤖 AI Code Generation: Uses Cursor Cloud Agents API for intelligent code generation
• 🔄 Automatic PRs: Cursor automatically creates pull requests with generated code
• ✅ Quality Standards: Follows project coding standards, includes tests, and proper error handling
• 🔁 Follow-up Support: Can add follow-up instructions to refine generated code

Architecture

┌─────────────┐
│ Jira Issue  │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  Jira Client     │ (Fetches issue details)
└──────┬───────────┘
       │
       ▼
┌─────────────────┐
│ Cursor Agent    │ (Launches Cursor cloud agent)
└──────┬───────────┘
       │
       ▼
┌─────────────────┐
│  Wait & Poll    │ (Monitors agent completion)
└──────┬───────────┘
       │
       ▼
┌─────────────────┐
│   PR Created    │ (Cursor creates PR automatically)
└─────────────────┘

Setup

Prerequisites

1. Jira API Token

   • Go to Jira → Account Settings → Security → API Tokens
   • Create a new API token
   • Store in GitHub Secrets as JIRA_API_TOKEN

2. Jira Email

   • Your Jira account email
   • Store in GitHub Secrets as JIRA_EMAIL

3. Jira Base URL

   • Your Jira instance URL (e.g., https://yourcompany.atlassian.net)
   • Store in GitHub Secrets as JIRA_BASE_URL

4. Cursor API Key

   • Get from Cursor Dashboard → API Keys
   • Create a new API key
   • Store in GitHub Secrets as CURSOR_API_KEY

Usage

As npm package (CLI)

After installing the package, you can use it as a CLI tool. The package includes a .env.example file—copy it to .env and fill in your values, or set the variables below.

# Set environment variables
export JIRA_ISSUE_KEY="PROJ-123"
export JIRA_API_TOKEN="your-token"
export JIRA_EMAIL="[email protected]"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export CURSOR_API_KEY="your-cursor-api-key"
export GITHUB_REPOSITORY="owner/repo"  # or full URL: https://github.com/owner/repo
export BASE_BRANCH="dev"

# Run the agent
npx autocode-dev
# or if installed globally: autocode-dev

In GitHub Actions Workflow

Create a workflow file (e.g., .github/workflows/ai-agent.yml):

name: Code Generation Agent

on:
  workflow_dispatch:
    inputs:
      jira_issue_key:
        description: 'Jira issue key (e.g., PROJ-123)'
        required: true
        type: string
  repository_dispatch:
    types: [jira-issue-updated]

jobs:
  generate-code:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install autocode-dev
        run: npm install -g autocode-dev

      - name: Extract Jira Issue Key
        id: extract-issue-key
        run: |
          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
            echo "issue_key=${{ github.event.inputs.jira_issue_key }}" >> $GITHUB_OUTPUT
          elif [ "${{ github.event_name }}" == "repository_dispatch" ]; then
            ISSUE_KEY="${{ github.event.client_payload.issue_key }}"
            echo "issue_key=${ISSUE_KEY}" >> $GITHUB_OUTPUT
          fi

      - name: Run AI Agent
        env:
          JIRA_ISSUE_KEY: ${{ steps.extract-issue-key.outputs.issue_key }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
          JIRA_EMAIL: ${{ secrets.JIRA_EMAIL }}
          JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          BASE_BRANCH: ${{ github.event.client_payload.base_branch || 'dev' }}
        run: autocode-dev

Manual Trigger (GitHub Actions)

1. Go to Actions → AI Agent → Run workflow
2. Enter the Jira issue key (e.g., PROJ-123)
3. Click "Run workflow"
4. Monitor the workflow logs to see agent progress
5. Once complete, check the PR URL in the logs

Via Jira Webhook (Automatic Trigger)

Configure a Jira webhook to automatically trigger when a ticket moves to "IN PROGRESS":

1. Go to Jira → Settings → System → Webhooks
2. Create a new webhook
3. URL: https://api.github.com/repos/{owner}/{repo}/dispatches
4. Events: Issue Updated (specifically when status changes)
5. Authentication: Use a GitHub Personal Access Token with repo scope
6. Webhook should POST JSON payload:

   {
     "event_type": "jira-issue-updated",
     "client_payload": {
       "issue_key": "{{issue.key}}",
       "status": "{{issue.fields.status.name}}"
     }
   }

7. Configure webhook to only trigger when status changes to "IN PROGRESS"

Note: The workflow will automatically:

• Generate code when ticket moves to "IN PROGRESS"
• Add PR link as a comment to the Jira ticket
• Move ticket to "IN REVIEW" after PR is created

Programmatic Usage

You can also use the package programmatically in your Node.js code:

import { main } from 'autocode-dev';

// Set environment variables before calling
process.env.JIRA_ISSUE_KEY = 'PROJ-123';
process.env.JIRA_API_TOKEN = 'your-token';
process.env.JIRA_EMAIL = '[email protected]';
process.env.JIRA_BASE_URL = 'https://yourcompany.atlassian.net';
process.env.CURSOR_API_KEY = 'your-cursor-api-key';
process.env.GITHUB_REPOSITORY = 'owner/repo';
process.env.BASE_BRANCH = 'dev';

await main();

Local Development (from source)

# Clone and setup
git clone https://github.com/Project-Clio/autocode-dev.git
cd autocode-dev
npm install
npm run build

# Set environment variables
export JIRA_ISSUE_KEY="PROJ-123"
export JIRA_API_TOKEN="your-token"
export JIRA_EMAIL="[email protected]"
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export CURSOR_API_KEY="your-cursor-api-key"
export GITHUB_REPOSITORY="owner/repo"  # or full URL: https://github.com/owner/repo
export BASE_BRANCH="dev"

# Run the agent
npm run dev

Configuration

The AI Agent requires the following environment variables:

| Variable | Description | Required | | ------------------- | ------------------------------------------ | -------- | | JIRA_ISSUE_KEY | Jira issue key (e.g., PROJ-123) | Yes | | JIRA_API_TOKEN | Jira API token | Yes | | JIRA_EMAIL | Jira account email | Yes | | JIRA_BASE_URL | Jira instance URL | Yes | | CURSOR_API_KEY | Cursor API key | Yes | | GITHUB_REPOSITORY | GitHub repository (owner/repo or full URL) | Yes | | BASE_BRANCH | Base branch for PR (default: dev) | No |

How It Works

1. Fetch Jira Issue: Retrieves issue details including summary, description, labels, etc.
2. Generate Branch Name: Creates a descriptive branch name from the Jira issue
   • Format: {issue-key}-{slugified-summary} (issue key first, for Jira branch linking)
   • Example: clio-39-add-user-authentication
   • The branch name is automatically generated from the issue summary to be meaningful and related to the work
3. Launch Cursor Agent:
   • Creates a prompt from the Jira issue details
   • Launches a Cursor cloud agent with the prompt
   • Creates a new branch with the generated name
   • Base branch is set to dev (configurable via BASE_BRANCH env var)
   • Cursor analyzes the codebase automatically
4. Monitor Progress:
   • Polls the agent status periodically (default every 30 seconds)
   • Waits for completion (default max 30 minutes, configurable)
5. Get Results:
   • Retrieves the PR URL when agent completes
   • PR merges into dev branch
   • Logs agent summary and status
6. Update Jira:
   • Adds PR link as a comment to the Jira ticket
   • Transitions ticket to "IN REVIEW" status

Generated Code Quality

The AI agent is configured to generate code that:

• ✅ Follows TypeScript strict typing
• ✅ Includes unit tests
• ✅ Passes ESLint rules
• ✅ Uses Prettier formatting
• ✅ Includes proper error handling
• ✅ Has JSDoc documentation
• ✅ Follows accessibility guidelines (for React components)

Follow-up Instructions

You can add follow-up instructions to refine the generated code:

const cursorClient = new CursorAgentClient(apiKey);
await cursorClient.addFollowUp(agentId, 'Also add error handling for edge cases');

Limitations

• Code generation is based on AI interpretation of requirements
• Generated code should always be reviewed before merging
• Complex features may require multiple iterations (use follow-up feature)
• Agent execution time varies (typically 2-10 minutes)
• Maximum wait time is 30 minutes by default (configurable when using the API)

Troubleshooting

"Failed to fetch Jira issue"

• Verify JIRA_API_TOKEN, JIRA_EMAIL, and JIRA_BASE_URL are correct
• Check that the issue key exists and is accessible

"Failed to launch Cursor agent"

• Verify CURSOR_API_KEY is valid
• Check that the repository URL is correct
• Ensure the base branch exists
• Review API response in logs for specific errors

"Agent did not complete"

• Check the agent URL in the logs to see current status
• Agents may take longer for complex tasks
• Consider increasing maxWaitTime if needed

"No PR URL found"

• Agent may have completed but PR creation failed
• Check the agent URL to see what was generated
• Verify repository permissions

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage (enforces thresholds)
npm run test:coverage

# Lint
npm run lint

# Fix linting issues
npm run lint:fix

# Format code (Prettier)
npm run format

# Check formatting without writing
npm run format:check

Maintainer: versioning and publishing

• Git hooks (Husky): On npm install, prepare runs Husky. Pre-commit runs npm run lint then lint-staged (Prettier, ESLint, and tests on staged src/**/*.ts). To skip hooks once: git commit --no-verify.

• CI: .github/workflows/ci.yml runs on push/PR to main: lint, format check, build, and test with coverage on Node 18, 20, 22.

• Node version: Use Node 18+ (see .nvmrc). Run nvm use if you use nvm.

• Changelog: Update CHANGELOG.md for each release (Keep a Changelog format). Use the full categories: Added, Changed, Deprecated, Removed, Fixed, Security.

• Versioning: We follow Semantic Versioning. See docs/VERSIONING.md for when to bump patch vs minor vs major.

• Bump version (without git tag): npm run version:patch | version:minor | version:major. Then commit and tag yourself, or use npm version patch (creates git tag).

• Before publish: Set repository, bugs, and homepage in package.json to your GitHub org/repo. Then npm run build and npm publish --dry-run to inspect the tarball.

• Publish: npm login then npm publish. For scoped packages use npm publish --access public.

• Release via GitHub Actions: The release workflow (.github/workflows/release.yml) publishes to npm when you push a version bump to main. You can use either an npm token (quick) or Trusted Publishing (recommended, no long-lived token).

  Option A – Token (first publish or fallback): Add a repository secret NPM_TOKEN (Settings → Secrets and variables → Actions). Create an npm Automation token (Classic → Automation). Do not enable “Bypass 2FA” if you prefer to use Trusted Publishing instead (see Option B).

  Option B – Trusted Publishing (recommended): No token stored in GitHub; npm uses short-lived OIDC credentials from the workflow. First: publish once with Option A so the package exists on npm. Then: on npmjs.com go to Packages → autocode-dev → Settings → Trusted publishing → Add trusted publisher → GitHub Actions. Enter:

  • Workflow filename: release.yml (must match exactly)
  • Save. After that you can remove the NPM_TOKEN secret; the workflow already has id-token: write and uses Node 22 so OIDC works.

API Reference

The public API is documented with JSDoc in the source; your IDE will show descriptions, parameters, and return types. Key exports:

main()

Runs the full workflow (fetch Jira issue → launch Cursor agent → wait for completion → update Jira). Reads configuration from environment variables. Exits with code 1 on failure.

CursorAgentClient

Main client for the Cursor Cloud Agents API.

Methods

• launchAgent(jiraIssue, config): Launches a new agent; returns agent id and target URL.
• getAgentStatus(agentId): Returns current agent status and target (e.g. prUrl when done).
• waitForCompletion(agentId, maxWaitTime?, pollInterval?): Polls until the agent finishes, fails, or is stopped; default max wait 30 minutes, poll every 30 seconds.
• addFollowUp(agentId, prompt): Sends a follow-up instruction to the agent.

JiraClient & fetchJiraIssue

• JiraClient: getIssue(issueKey), addComment(issueKey, comment), getTransitions(issueKey), transitionIssue(issueKey, transitionId), transitionIssueToStatus(issueKey, targetStatusName).
• fetchJiraIssue(issueKey, baseUrl, email, apiToken): Helper that creates a client and fetches one issue.

License

MIT - see LICENSE for details.