Fix bugs faster with CircleCI’s Chunk AI agent

Bugs hide in plain sight. A date validator that rejects February 29th on leap years. An edge case that slips through code review. A flaky test that passes locally but fails in CI. These issues erode trust in your codebase and waste hours of debugging time.

In the era of AI-assisted development, code is being written faster than ever. But speed creates risk. When AI coding assistants generate code quickly, subtle bugs can slip through, and the feedback loop between writing code and discovering issues can stretch across multiple commits. The longer a bug lives in your codebase, the harder it is to fix.

Chunk, CircleCI’s autonomous CI/CD agent, brings AI capabilities directly into your continuous integration pipeline where bugs are discovered. Unlike IDE-based tools, Chunk has access to your build history, test results, and failure patterns across your entire pipeline history. It can identify bugs, diagnose root causes, and generate fixes automatically. In this guide, you’ll learn how to use Chunk to fix bugs faster.

Setting up Chunk

To get started with Chunk, you’ll need a CircleCI account with a project already running pipelines. If you’re new to CircleCI, check out the getting started guide to connect your repository.

You can follow along with your own project or use our demo project on GitHub if you’d like a ready-made example.

Once your project is running in CircleCI:

1. Go to Chunk in the CircleCI web app sidebar.
2. Click Set up Chunk and follow the prompts to authorize GitHub access. Chunk requires read access to analyze your repository and write access to create pull requests with its fixes.
3. Connect your Anthropic or OpenAI API key when prompted. Chunk uses your own API credentials, so your code is never sent to external providers for model training and data stays under your control.

Chunk integrates directly with your existing CircleCI pipelines without requiring any reconfiguration. Once authorized, it can analyze both your repository code and your build history to understand how your project works. For complete setup instructions, see the Chunk documentation.

Asking Chunk to fix bugs

With Chunk enabled, navigate to Chunk in the sidebar. You’ll see a prompt interface where you can describe what you want Chunk to do.

Start with a simple prompt:

Fix bugs

Click Submit and Chunk begins working. Because Chunk operates within your CI/CD environment, it has access to your test history, failure logs, and patterns across multiple pipeline runs. It uses this data to identify potential bugs and edge cases, examine the source code to understand what’s going wrong, and generate targeted fixes.

Reviewing the results

When Chunk completes its analysis, you’ll see a summary of what bugs it found and the fixes it generated. From this page, you can review the details and decide whether to open a pull request. If you’re not satisfied with the changes, you can skip the PR and refine your prompt instead.

Chunk explains its findings and changes:

Summary
Added leap year logic to the date validator to correctly handle
February 29th on leap years.

Changes
Added leap year calculation based on standard rules (divisible by 4,
except centuries unless divisible by 400)

Updated maxDay for February to be 29 on leap years instead of always 28

Changed maxDay from const to let to allow reassignment for leap years

If the changes look good, click Open Pull Request to create a PR in your repository.

Before merging, review the generated fixes to ensure they correctly address the bug without introducing new issues.

More targeted prompts

The simple “Fix bugs” prompt works well for general bug hunting. For more control over what Chunk investigates, try targeted prompts.

To target flaky tests specifically, run:

Fix flaky tests in the test suite

To focus on a specific module, run:

Fix the failing tests in src/processors/batch.js

To diagnose without fixing, run:

Analyze the flaky tests and explain why they're failing, but don't
make changes yet

To fix a specific error pattern, run:

Fix the timeout errors in the pipeline processor tests

The more specific you make your prompt, the more targeted Chunk’s analysis will be.

Advanced configuration

Once you’re comfortable with the basics, you can fine-tune how Chunk operates with your project.

Environment setup

For projects with complex dependencies, external services, or specific runtime requirements, you can provide a .circleci/cci-agent-setup.yml file that tells Chunk exactly how to prepare your test environment.

This is particularly important for bug fixing because Chunk needs to reproduce failures accurately. Common use cases include:

• Database setup: If bugs involve database interactions, Chunk needs access to the same database configuration your tests use
• External services: Redis, message queues, or other services that might be involved in race conditions or timing issues
• Environment variables: API keys, feature flags, or configuration that affects code behavior
• Specific runtime versions: If bugs are version-specific, matching your production environment matters

Here’s an example for a Python project with PostgreSQL:

version: 2.1

workflows:
  main:
    jobs:
      - cci-agent-setup

jobs:
  cci-agent-setup:
    docker:
      - image: cimg/python:3.12
      - image: cimg/postgres:15.3
    steps:
      - checkout
      - run:
          name: Install Dependencies
          command: pip install -r requirements.txt
      - run:
          name: Setup Database
          command: |
            psql -c "CREATE DATABASE test_db;" -U postgres

Focus on environment preparation only. Don’t include actual test execution commands. Chunk will determine how to run tests based on your main config.yml.

Chunk will attempt to automatically create this file if needed. You can also manually generate one. Go to Organization Settings -> Chunk Tasks. Click the menu (…) for your task. Click Chunk Environment, then click Create File in GitHub. For more details, see the Chunk environment documentation.

Custom instructions

To guide how Chunk approaches bug fixes, create a claude.md or agents.md file in your repository root. You can document your preferences for:

• How to handle timing-sensitive tests (use mocks vs. increase timeouts)
• Preferred patterns for async test handling
• Whether to add retry logic or fix the underlying issue
• Logging and debugging conventions

Chunk reads these files and applies your preferences when generating fixes.

Test history analysis

Chunk’s bug detection improves over time as it analyzes your test history. Ensure your CircleCI config includes store_test_results so Chunk can identify patterns across multiple pipeline runs. Tests that fail intermittently are flagged as flaky, even if they passed in the most recent build. This historical analysis is one of the key advantages of having an AI agent embedded in your CI/CD pipeline rather than operating only on static code.

Chunk in the AI development ecosystem

While AI coding assistants help you write code faster in your IDE, Chunk operates at the CI/CD layer where bugs are actually discovered and validated.

This positioning is strategic. Your CI/CD pipeline is where code meets reality. It’s where tests run against real dependencies, where race conditions surface under load, and where edge cases that seemed theoretical become concrete failures. By embedding AI at this layer, Chunk can act on information that IDE-based tools simply don’t have access to.

For teams using AI coding assistants, CircleCI also offers the CircleCI MCP Server, which connects AI assistants directly to your pipelines using the Model Context Protocol. When a build fails, your AI assistant can fetch the logs, understand what went wrong, and suggest fixes without you ever leaving your editor. Together, Chunk and the MCP server create an integrated AI development workflow where bugs are caught in CI and can be debugged from anywhere.

Conclusion

Bugs don’t have to drain your team’s productivity. Chunk analyzes your codebase and pipeline history, identifies issues like missing edge cases and logic errors, diagnoses root causes, and generates fixes that make your code more robust. As AI-powered development accelerates the pace of code changes, having an autonomous agent that catches and fixes bugs becomes essential for maintaining code quality.

Ready to try it yourself? Sign up for a free CircleCI account and enable Chunk to start fixing bugs automatically.