Sweep AI

Sweep AI is an autonomous code agent that writes, reviews, and maintains code across a repository. It runs as a continuous background process, responding to git events, pull requests, and direct commands. It matters when developers need consistent, high-quality code without manual oversight—especially in teams with distributed contributors or fast release cycles.

Creating and Managing Pull Requests

Sweep AI automatically creates pull requests (PRs) based on tasks, issues, or feature branches. When a new branch is pushed with a feat/ prefix, Sweep AI detects it and opens a PR with a detailed description.

git checkout -b feat/user-authentication

git commit -m "feat: add user authentication with JWT"
git push origin feat/user-authentication

Sweep AI reads the commit message and generates a PR title and description using a combination of natural language processing and code context. It includes a summary of changes, links to related issues, and a table of proposed changes.

The PR is created with the following metadata in the pull_request field of the sweep.yaml configuration file:

# .sweep/sweep.yaml
pull_request:
  title: "feat: add user authentication with JWT"
  body: |
    This PR introduces JWT-based user authentication to the API.

    - Adds `/auth/login` endpoint
    - Implements JWT token refresh
    - Adds middleware to validate tokens
    - Updates tests for authentication flow

  assignees:
    - johndoe
    - sally
  reviewers:
    - alice
    - dev-team
  labels:
    - feature
    - api
    - security
  draft: true

Sweep AI applies the PR template from .github/pull_request_template.md and enriches it with a changelog snippet and a list of detected code changes using git diff and grep.

When a PR is opened, Sweep AI runs a pre-merge check that includes:

• Linting with eslint --fix
• Formatting with prettier --write
• Running tests with npm test
• Building the app with npm run build

Failure in any step adds a status check to the PR, with a link to the full CI log.

Reviewing Code Changes

Sweep AI reviews pull requests by analyzing the diff, context, and project history. It generates comments directly on the PR with line-by-line feedback.

For every code change, it suggests improvements using a set of rules and patterns learned from the codebase. It identifies common issues such as:

• Missing error handling in API routes
• Unnecessary complexity in utility functions
• Inconsistent naming or formatting
• Performance bottlenecks

A typical review comment:

🔍  [Sweep AI] Add missing error handling in user login endpoint

In `src/api/auth.ts`, you’re calling `await db.query(...)` but not wrapping it in a try-catch block.

Suggestion:
```ts
async function loginUser(email: string, password: string) {
  try {
    const user = await db.query('SELECT * FROM users WHERE email = ?', [email]);
    if (!user) {
      throw new Error('User not found');
    }
    // ... rest of logic
  } catch (err) {
    logger.error('Login failed', { email, error: err });
    throw new Error('Authentication failed');
  }
}

This improves error visibility in logs and reduces downtime during authentication failures.

💡 Suggested: Add unit test for edge case (e.g., invalid email format).

Sweep AI applies these reviews automatically via GitHub Actions. The review process runs in a `sweep-review` job defined in `.github/workflows/sweep-review.yml`:

```yaml
name: Sweep Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm install
      - name: Run Sweep AI review
        run: |
          npx sweep@latest review --pr ${{ github.event.pull_request.number }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SWEET_API_KEY: ${{ secrets.SWEET_API_KEY }}

The sweep review command supports the following flags:

sweep review --pr 42 --verbose --context-depth 3 --no-ai-comments

• --pr <number>: the pull request number to review.
• --verbose: includes detailed logs, including file analysis and rule evaluation.
• --context-depth <n>: increases the amount of surrounding code considered for each change.
• --no-ai-comments: disables AI-generated suggestions, using only rule-based feedback.

When a reviewer replies to a Sweep AI comment with @Sweep AI: rebase, Sweep AI automatically rebases the PR branch and updates the PR body with a summary of changes.

Automating Code Tasks

Sweep AI handles recurring tasks through a declarative task definition in sweep.tasks.yaml:

# .sweep/sweep.tasks.yaml
tasks:
  - name: "Daily code cleanup"
    description: "Run lint, format, and test on all files"
    schedule: "0 8 * * *"
    command: |
      npm run lint -- --fix
      npm run format
      npm run test -- --watchAll=false
    trigger:
      - branch: "main"
      - event: "push"
    dependencies:
      - "ci-build"
      - "deploy-prod"
    context:
      - "src/**/*.ts"
      - "test/**/*.spec.ts"

Tasks are executed by a sweep run command, which reads the task configuration and runs each task in sequence.

sweep run --task "Daily code cleanup"

Each task runs in a dedicated container using Docker, with the following environment:

• NODE_ENV=production
• SWEET_LOG_LEVEL=info
• SWEET_TASK_ID=2024-10-03-daily-cleanup

Sweep AI logs execution details to logs/sweep-<task-id>.log, including the command executed, duration, and any errors.

If a task fails, it creates a new issue in the repository with the title Task failed: <task name> and attaches the full log output.

Handling Issues and Bug Reports

When a new issue is opened or updated, Sweep AI parses the issue content and assigns it to relevant team members based on code ownership and past contributions.

For example, an issue titled User cannot log in after password reset triggers a workflow that:

1. Queries the database for recent password reset events.
2. Analyzes src/api/auth.ts for the login flow.
3. Suggests a fix based on common patterns in the codebase.

Sweep AI generates a response with a proposed solution and opens a PR with the fix.

🔧  [Sweep AI] Fix: User cannot log in after password reset

Summary:
After password reset, users receive a token but cannot log in. The issue stems from the `loginUser` function not validating the reset token before setting the new password.

Proposed fix:
- Add `validateResetToken` helper function
- Call it in `loginUser` before updating the user
- Add test case for reset token validation

PR: #51

The PR includes the following changes:

// src/api/auth.ts
export async function validateResetToken(token: string): Promise<boolean> {
  const result = await db.query(
    'SELECT * FROM password_resets WHERE token = ? AND expires_at > NOW()',
    [token]
  );
  return result.length > 0;
}

export async function loginUser(email: string, password: string) {
  const user = await db.query('SELECT * FROM users WHERE email = ?', [email]);
  if (!user) {
    throw new Error('User not found');
  }

  const validToken = await validateResetToken(password); // use password as reset token
  if (!validToken) {
    throw new Error('Reset token is invalid or expired');
  }

  // ... continue with login logic
}

Sweep AI also links to related issues, adds a fixes keyword in the PR body, and updates the original issue with a status update.

Maintaining the Codebase

Sweep AI runs periodic maintenance tasks, such as updating dependencies and refactoring code.

To update dependencies, it uses sweep update:

sweep update --package-manager npm --update-strategy "minor"

This command:

• Reads package.json
• Fetches the latest versions of all packages
• Creates a PR with npm update --save and npm install
• Applies a versioning strategy: patch, minor, or major

For example, with --update-strategy minor, it updates all packages with a new minor version, but keeps patch versions unchanged.

// package.json
{
  "dependencies": {
    "express": "^4.18.2",
    "pg": "^8.11.0",
    "zod": "^3.21.0"
  }
}

Sweep AI updates express to ^4.19.0, pg to ^8.12.0, and zod to ^3.22.0.

It also applies code refactoring tasks defined in sweep.refactor.yaml:

# .sweep/sweep.refactor.yaml
refactors:
  - name: "Rename user model fields"
    description: "Standardize field names across user model"
    files:
      - "src/models/User.ts"
      - "src/api/userRoutes.ts"
    changes:
      - rename: "userId" to "id"
      - rename: "userEmail" to "email"
      - rename: "userCreatedAt" to "createdAt"
    pattern: "snake_case"
    commit-message: "refactor: standardize user field names"

Sweep AI performs the refactor by scanning all specified files, applying the rename operations, and committing the changes with a summary.

Troubleshooting and Failure Modes

Sweep AI silently fails when it cannot access the codebase or configuration. Common issues include:

• sweep.yaml not found in root directory
• Missing SWEET_API_KEY in environment
• PR not updated due to GitHub API rate limiting

The most common error is PR not updated: failed to fetch pull request with the following JSON response:

{
  "error": "PR not updated",
  "code": "PR_FETCH_FAILED",
  "details": {
    "pr_number": 42,
    "api_url": "https://api.github.com/repos/owner/repo/pulls/42",
    "status": 403,
    "response": {
      "message": "API rate limit exceeded for user",
      "documentation_url": "https://docs.github.com/rest"
    }
  }
}

Sweep AI retries the operation after a backoff period, using exponential backoff with jitter.

Another silent failure occurs when a task runs but no logs are generated. The cause is usually a misconfigured logs directory path or missing sweep binary in the PATH.

Sweep AI also fails to detect changes when the git log output is inconsistent. It assumes that the HEAD commit is always the most recent, but if git push is not followed by git fetch, the PR may be created with stale changes.

The sweep run command has a subtle behavior: if a task has dependencies, it runs them in the order specified, but only if the dependencies have completed successfully. If a dependency fails, the task is marked as failed and no further steps are executed.

Finally, Sweep AI applies formatting to code but does not detect conflicts during a merge. When a PR is merged, it checks for formatting conflicts by comparing git diff --cached with the expected format. If the changes differ, it creates a formatting-mismatch issue and adds a comment to the PR:

⚠️  [Sweep AI] Formatting mismatch detected

The PR was formatted with `prettier`, but the final commit does not match the expected format.

Expected:
```ts
function greet(name: string) {
  console.log(`Hello, ${name}`);
}

Actual:

function greet(name: string) {
console.log(`Hello, ${name}`);
}

Please reformat and push the changes.

Sweep AI can be configured to auto-apply these formatting fixes by running `prettier --write` and pushing the result.

This page was rewritten on 14 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.