AutoAgent

⚠️ Experimental Project: This project was created during a hackathon at the Cursor offices on September 10, 2025. Use at your own risk. Future updates will focus on making it production CI/CD ready. 🚧 - Thank you to the Curosr team for hosting!

A composable GitHub Action that integrates with AI agents like Cursor CLI, Claude Code, Gemini CLI, Codex CLI, Amp Code, and OpenCode to run prompts on a repository as part of Pull Request workflows.

Features

• Predefined Rules: Run curated rules like OWASP security checks or refactoring suggestions
• Custom Prompt Support: Extend analysis with team-specific custom instructions
• Agent Auto Installation: Automatically installs the agent unless explicitly disabled
• Multiple Agents Support: Supports multiple AI coding agents: cursor, claude, gemini, codex, amp, and opencode
• Configurable Scope: Analyze only changed files (fast) or entire codebase (comprehensive)
• PR Comment Output: Posts results back to GitHub PR comments in a structured format
• Composable Python Architecture: Built with maintainable, modular Python code for better reliability and extensibility
• Configurable Logging: Debug mode for troubleshooting with detailed execution information

Suggested Future Work

I would love to get feedback if this is working well and if any of these future work items seems relevant to you:

1. Ability to stop merge if there are high vulnerability items in AutoAgent - Block PRs automatically when critical security issues are detected
2. Ability to have other actions other than commenting - Support for email notifications, Slack messages, or other integrations for important findings
3. Ability to fail a build if AutoAgent has important enough failures - Set exit codes based on severity levels to integrate with CI/CD pipeline failure conditions
4. Ability to execute rules in parallel - Run multiple rules concurrently to reduce overall analysis time and improve CI/CD performance

Usage

Basic Example with Cursor

name: AutoAgent Checks

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          custom: |
            Please check for inefficient SQL queries and suggest optimizations.
          action: comment
          install-agent: true
          agent: cursor

Example with Claude Code

name: AutoAgent with Claude

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          custom: |
            Please check for inefficient SQL queries and suggest optimizations.
          action: comment
          install-agent: true
          agent: claude

Example with Gemini CLI

name: AutoAgent with Gemini

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          custom: |
            Please check for inefficient SQL queries and suggest optimizations.
          action: comment
          install-agent: true
          agent: gemini

Example with Codex CLI

name: AutoAgent with Codex

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          custom: |
            Please check for inefficient SQL queries and suggest optimizations.
          action: comment
          install-agent: true
          agent: codex

Example with Amp Code

name: AutoAgent with Amp

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          AMP_API_KEY: ${{ secrets.AMP_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          custom: |
            Please check for inefficient SQL queries and suggest optimizations.
          action: comment
          install-agent: true
          agent: amp

Example with OpenCode

OpenCode supports multiple AI providers (Anthropic, OpenAI, Google, etc.) and automatically uses the appropriate API key based on the model you specify:

name: AutoAgent with OpenCode

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
          MODEL: anthropic/claude-sonnet-4-20250514
        with:
          rules: |
            - owasp-check
            - code-review
          custom: |
            Please check for inefficient SQL queries and suggest optimizations.
          action: comment
          install-agent: true
          agent: opencode

OpenCode Model Examples

You can specify different providers and models:

# Using Anthropic Claude
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  MODEL: anthropic/claude-sonnet-4-20250514

# Using OpenAI GPT
env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  MODEL: openai/gpt-4

# Using Google Gemini
env:
  GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
  MODEL: google/gemini-pro

Analysis Scope Configuration

AutoAgent supports two analysis modes controlled by the scope parameter:

🚀 Changed Files Mode (Default) - scope: "changed"

This mode analyzes only files that have been modified in the Pull Request, making it faster and more cost-effective by focusing AI analysis on the actual changes.

How it works:

• Automatically detects all files changed in the PR across all commits
• Uses multiple git diff strategies for maximum compatibility
• Provides changed file list context to AI agents
• Falls back to GitHub API when git history is insufficient
• Works with merge commits, rebases, and complex PR scenarios

Key Benefits:

• ⚡ Faster execution - Only processes changed files
• 💰 Token efficient - Reduces API costs significantly
• 🎯 Focused analysis - AI concentrates on actual changes
• 🔄 Auto-detection - Handles complex git scenarios automatically

Requirements for Changed Files Mode:

• Must use fetch-depth: 0 in checkout action (see examples below)
• Requires GitHub CLI (gh) for API fallback
• Works best with proper base branch setup

Analyze Only Changed Files (Default - Faster)

name: AutoAgent - Changed Files Only

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for proper changed file detection
      - name: Run AutoAgent on Changed Files
        uses: erans/autoagent@main
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          scope: "changed"  # This is the default
          action: comment
          agent: cursor

🔍 Full Codebase Mode - scope: "all"

This mode performs comprehensive analysis of the entire repository codebase, useful for security audits, architectural reviews, or when you need complete coverage.

When to use:

• Security audits requiring full codebase review
• Architectural analysis and refactoring suggestions
• Initial code quality assessment
• Compliance reviews and documentation checks

Trade-offs:

• ⏱️ Slower execution - Processes entire codebase
• 💸 Higher cost - Uses more API tokens
• 📊 Comprehensive coverage - No missed dependencies or context
• 🔎 Deep analysis - Can catch broader architectural issues

Analyze Entire Codebase (Comprehensive)

name: AutoAgent - Full Codebase Analysis

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for proper changed file detection
      - name: Run AutoAgent on Entire Codebase
        uses: erans/autoagent@main
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          scope: "all"  # Analyze entire codebase
          action: comment
          agent: cursor

Troubleshooting Changed Files Detection

If you see "No changed files detected" in the output, enable debug logging first to get detailed information:

- name: Run AutoAgent with Debug
  uses: erans/autoagent@main
  with:
    logging: debug  # Enable detailed debugging
    # ... other parameters

Then try these solutions based on the debug output:

Issue: Shallow Clone

# ❌ This may cause detection issues
- uses: actions/checkout@v4

# ✅ Use this instead
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Required for changed file detection

Issue: Missing Base Branch

The action automatically fetches the base branch, but ensure your workflow runs on pull request events:

on:
  pull_request:
    types: [opened, synchronize, reopened]  # All required events

Issue: Complex Merge Scenarios

AutoAgent uses 8 different detection strategies including:

• Merge-base calculation
• GitHub API fallback
• Merge commit detection
• Multiple git diff approaches

Check the debug output to see which strategy succeeded.

Issue: Permissions

Ensure your workflow has proper permissions:

permissions:
  contents: read        # Required for checkout
  pull-requests: write  # Required for comments
  issues: write         # Required for GitHub API

Advanced Example

name: AutoAgent Security & Quality Checks

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
            - refactor-suggestions
            - duplication-check
          custom: |
            Please analyze the database schema changes and ensure they follow our naming conventions.
            Also check for any potential performance issues with the new queries.
          action: comment
          install-agent: true
          agent: cursor

Custom Prompt Only Example

name: AutoAgent Custom Analysis

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AutoAgent
        uses: erans/autoagent@main
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        with:
          custom: |
            Please review this pull request for:
            1. Code quality and best practices
            2. Security vulnerabilities
            3. Performance optimizations
            4. Documentation completeness
          action: comment
          install-agent: true
          agent: cursor

Debug Logging Example

Enable debug logging to troubleshoot issues with file detection, agent execution, or other problems:

name: AutoAgent with Debug Logging

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for proper changed file detection
      - name: Run AutoAgent with Debug Output
        uses: erans/autoagent@main
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          logging: debug  # Enable detailed debugging output
          agent: cursor

Debug logging includes:

• Detailed git diff strategies and results
• Changed file detection process
• Agent execution details and prompt lengths
• Rule processing steps and timings
• Error details and troubleshooting information

Custom Rule Files Examples

AutoAgent supports custom rule files through the customFiles parameter, allowing you to create reusable, organization-specific analysis rules.

Basic Custom Files Example

name: AutoAgent with Custom Rules

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  autoagent:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run AutoAgent with Custom Files
        uses: erans/autoagent@main
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        with:
          rules: |
            - owasp-check
            - code-review
          customFiles: |
            - .github/rules/team-standards.prompt
            - .github/rules/api-guidelines.prompt
          agent: cursor

Repository-Specific Rules

Create custom rule files in your repository under .github/rules/:

.github/rules/team-standards.prompt:

Review the code for adherence to our team's coding standards:

## API Design Standards
- All API endpoints must use consistent naming (kebab-case)
- Response structures must include status, data, and meta fields
- Error responses must follow RFC 7807 problem details format

## Database Standards
- All queries must use prepared statements
- Table names must be snake_case
- Foreign key relationships must be explicitly defined

## Testing Requirements
- All public methods must have unit tests
- Integration tests required for API endpoints
- Test coverage must be > 80%

Provide specific violations found with file locations and recommended fixes.

.github/rules/api-guidelines.prompt:

Analyze the API implementation for compliance with our guidelines:

## REST API Standards
- Proper HTTP status codes usage
- Consistent error handling patterns
- Request/response validation
- Rate limiting implementation

## Security Requirements
- Input sanitization for all endpoints
- Authentication middleware on protected routes
- SQL injection prevention
- XSS protection measures

Report any deviations from these standards with specific remediation steps.

Shared Organization Rules

Use relative paths to reference shared rules from a parent directory or organization-wide rule repository:

- name: Run AutoAgent with Shared Org Rules
  uses: erans/autoagent@main
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  with:
    customFiles: |
      - ../shared-rules/org-security.prompt
      - ../shared-rules/performance-standards.prompt
      - .github/rules/local-overrides.prompt
    agent: cursor

Mixed Rules Configuration

Combine predefined rules, custom files, and custom prompts:

- name: Comprehensive AutoAgent Analysis
  uses: erans/autoagent@main
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  with:
    rules: |
      - owasp-check
      - secrets-detection
    customFiles: |
      - .github/rules/team-standards.prompt
      - .github/rules/performance-check.prompt
    custom: |
      Additionally, please verify that all new database migrations
      include proper rollback procedures and performance impact analysis.
    agent: cursor

JSON Format Support

CustomFiles also supports JSON array format:

- name: AutoAgent with JSON Custom Files
  uses: erans/autoagent@main
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  with:
    customFiles: '["./rules/custom.prompt", ".github/rules/standards.prompt"]'
    agent: cursor

File Path Resolution

• Relative paths: Resolved relative to the repository root ($GITHUB_WORKSPACE)

  • ./rules/custom.prompt → $GITHUB_WORKSPACE/rules/custom.prompt
  • .github/rules/team.prompt → $GITHUB_WORKSPACE/.github/rules/team.prompt
  • ../shared/rule.prompt → Parent directory of workspace

• Absolute paths: Used as-is (with security validation)

  • /home/runner/work/shared/rule.prompt

• Security features:

  • File existence and readability validation
  • File size limits (max 1MB per file)
  • Path traversal protection
  • Graceful error handling for invalid files

Rule Naming in Comments

Custom rule files appear in PR comments using just the filename (without path or .prompt extension):

• .github/rules/team-standards.prompt appears as team-standards
• ../shared/org-security.prompt appears as org-security
• /absolute/path/api-check.prompt appears as api-check

Inputs

Predefined Rules

Output

The action posts structured results to the GitHub PR as comments:

### 🤖 AutoAgent Results

**Rule:** `owasp-check`

No critical security issues detected.

**Rule:** `code-review`

Found 2 potential improvements in the authentication logic.

**Rule:** `custom`

Database queries look optimized. Consider adding indexes for the new columns.

---
*Generated by [AutoAgent](https://github.com/erans/autoagent) v1.0*

Requirements

• GitHub CLI (gh) must be available in the runner environment
• For YAML parsing: yq (optional, falls back to jq)
• For JSON parsing: jq
• Node.js - Required for installing npm-based agents (Claude, Gemini, Codex)
• API Key - Required for your chosen agent (see Environment Variables section)
• Git History - Use fetch-depth: 0 in checkout action for proper changed file detection

Environment Variables

Required (based on agent):

• CURSOR_API_KEY - Required for Cursor CLI authentication
• ANTHROPIC_API_KEY - Required for Claude Code authentication
• GOOGLE_API_KEY - Required for Gemini CLI authentication
• OPENAI_API_KEY - Required for Codex CLI authentication
• AMP_API_KEY - Required for Amp Code authentication

OpenCode Multi-Provider Support:

OpenCode supports multiple AI providers. Set the appropriate API key(s) based on the model you want to use:

• ANTHROPIC_API_KEY - For Anthropic Claude models (anthropic/claude-sonnet-4-20250514)
• OPENAI_API_KEY - For OpenAI models (openai/gpt-4, openai/o1)
• GOOGLE_API_KEY - For Google Gemini models (google/gemini-pro)
• GROQ_API_KEY - For Groq models (groq/llama-3-70b)
• COHERE_API_KEY - For Cohere models (cohere/command-r)
• MISTRAL_API_KEY - For Mistral models (mistral/large)

Optional:

• MODEL - Optional AI model to use. Defaults vary by agent:
  • Cursor: gpt-5
  • Claude: claude-sonnet-4-20250514 (also supports claude-opus-4-1-20250805, claude-3-5-haiku-20241022)
  • Gemini: pro (also supports flash)
  • Codex: gpt-5 (also supports o3, o1)
  • Amp: sonnet-4 (also supports gpt-5)
  • OpenCode: anthropic/claude-sonnet-4-20250514 (supports 75+ models across providers)

Permissions

The action requires the following GitHub token permissions:

permissions:
  contents: read
  pull-requests: write
  issues: write

Add this to your workflow file to ensure the action can post comments to pull requests.

Setup

1. Add API Key Based on Your Agent

The action requires an API key environment variable to be set as a repository secret based on the agent you choose:

For Cursor Agent:

1. Get your Cursor API key:

   • Open Cursor IDE
   • Go to Settings (Cmd/Ctrl + ,)
   • Navigate to General → Account
   • Copy your API key from the account section

2. Add the secret: Add CURSOR_API_KEY as a repository secret

For Claude Code:

1. Get your Anthropic API key:

   • Go to Anthropic Console
   • Navigate to API Keys
   • Create a new API key or copy an existing one

2. Add the secret: Add ANTHROPIC_API_KEY as a repository secret

For Gemini CLI:

1. Get your Google API key:

   • Go to Google AI Studio
   • Create a new API key or use an existing one
   • Alternatively, authenticate with Google login (free tier: 60 requests/minute)

2. Add the secret: Add GOOGLE_API_KEY as a repository secret

For Codex CLI:

1. Get your OpenAI API key:

   • Go to OpenAI Platform
   • Create a new API key or use an existing one
   • Alternatively, sign in with your ChatGPT account (Plus, Pro, Team, Edu, or Enterprise)

2. Add the secret: Add OPENAI_API_KEY as a repository secret

For Amp Code:

1. Get your Amp API key:

   • Go to Amp Code
   • Sign up or log in to your account
   • Run amp login in your terminal to authenticate
   • Your API key will be stored locally and can be found in the credentials file

2. Add the secret: Add AMP_API_KEY as a repository secret

For OpenCode:

OpenCode supports multiple AI providers, so you can set up one or more API keys based on which models you want to use:

1. For Anthropic Claude models (recommended):

   • Go to Anthropic Console
   • Navigate to API Keys
   • Create a new API key or copy an existing one
   • Add ANTHROPIC_API_KEY as a repository secret

2. For OpenAI models:

   • Go to OpenAI Platform
   • Create a new API key or use an existing one
   • Add OPENAI_API_KEY as a repository secret

3. For Google Gemini models:

   • Go to Google AI Studio
   • Create a new API key or use an existing one
   • Add GOOGLE_API_KEY as a repository secret

4. For other providers (optional):

   • Groq: Get API key from Groq Console → Add GROQ_API_KEY
   • Cohere: Get API key from Cohere Dashboard → Add COHERE_API_KEY
   • Mistral: Get API key from Mistral Platform → Add MISTRAL_API_KEY

5. Set the model: Use the MODEL environment variable to specify which provider/model to use:

   • anthropic/claude-sonnet-4-20250514 (default)
   • openai/gpt-4
   • google/gemini-pro
   • groq/llama-3-70b
   • And many more...

Steps to add any secret to your repository:

• Go to your GitHub repository
• Click Settings (in the repository toolbar)
• In the left sidebar, click Secrets and variables → Actions
• Click New repository secret
• Name: Use the appropriate key name for your agent
• Value: Paste your API key
• Click Add secret

Important: The API key must be added as a repository secret, not as an environment variable in the workflow file directly.

2. Add Workflow Permissions

Add the permissions block to your workflow file (see Permissions section above).

Error Handling

The action will fail gracefully with descriptive error messages for:

• Missing rule files
• Agent installation failures
• Invalid input formats
• Missing required tools

License

MIT License - see LICENSE file for details.