# How to Configure Auto-Retry and Quality Gates in Prime Agent Autonomous Mode

> Master Prime Agent autonomous mode. Configure auto-retry and quality gates using autonomous.gates.commands and autonomous.gates.maxRetries for seamless agent operations and robust validation.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-12

---

**Configure auto-retry and quality gates in Prime Agent by setting `autonomous.gates.commands` for validation checks and `autonomous.gates.maxRetries` to automatically re-run failed turns up to a specified limit.**

Prime Agent's **autonomous mode** enables the agent to execute multiple turns without human intervention until configured limits or quality gates trigger a stop. Understanding how to configure **auto-retry behavior** and **quality gate validation** ensures reliable, self-correcting automation workflows. This configuration is managed through the `AutonomousConfig` interface and runtime state in [`packages/coding-agent/src/core/autonomous.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/autonomous.ts).

## Understanding Quality Gates in Prime Agent

Quality gates are **shell commands executed after each autonomous turn** that validate the agent's work. The agent invokes these commands and inspects the exit code to determine whether to continue or halt.

### How Quality Gates Work

In [`packages/coding-agent/src/core/autonomous.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/autonomous.ts), the `refreshAutonomousQualityGates` function manages gate execution:

- Gates must **exit with status 0** to permit continuation
- **Non-zero exits trigger retry evaluation** (if `maxRetries > 0`)
- Gates run with a configurable **timeout** (`timeoutMs`)

Quality gates typically include:
- **Linting**: `npm run lint`, `eslint .`, `flake8`
- **Type checking**: `tsc --noEmit`, `mypy`
- **Tests**: `npm test`, `pytest`
- **Custom validation scripts**: project-specific checks

## Configuring Auto-Retry Behavior

Auto-retry is controlled by the `maxRetries` field within `autonomous.gates`. When a gate fails, Prime Agent automatically re-executes the turn **provided the workspace has changed**, tracked in `AutonomousRuntimeState.gateAttempts`.

### Retry Mechanics

The retry flow in `nextAutonomousContinuation` (from [`autonomous.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/autonomous.ts)) follows these steps:

1. Compare current retry count (`state.gateAttempts[gateId]`) against `maxRetries`
2. Check if workspace state changed since last attempt
3. If both conditions pass, inject a new autonomous continuation via `addAutonomousContinuation`
4. If retries exhausted, set limit reason to `"retry_exhausted"` and stop

**Critical distinction**: Retries consume **autonomous continuations** but do not increment the turn counter until the retry budget is exhausted.

## Complete Configuration Reference

| Setting | Path | Description | Default |
|---------|------|-------------|---------|
| `enabled` | `autonomous.enabled` | Master switch for autonomous mode | `false` |
| `commands` | `autonomous.gates.commands` | Array of shell commands to run post-turn | `[]` |
| `maxRetries` | `autonomous.gates.maxRetries` | Retry attempts per gate failure | `0` |
| `timeoutMs` | `autonomous.gates.timeoutMs` | Per-gate execution timeout | `30000` |
| `maxContinuations` | `autonomous.limits.maxContinuations` | Total autonomous continuations allowed | `Infinity` |
| `maxTurns` | `autonomous.limits.maxTurns` | Maximum turns before auto-stop | `Infinity` |
| `maxTokens` | `autonomous.limits.maxTokens` | Token budget for autonomous runs | `Infinity` |
| `timeoutMs` | `autonomous.limits.timeoutMs` | Global timeout for entire run | `Infinity` |

These defaults are defined in `DEFAULT_AUTONOMOUS_GATES` and merged via `mergeAutonomousConfig` in [`packages/coding-agent/src/core/agent-session-config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session-config.ts).

## Configuration Methods

Prime Agent supports three configuration pathways, all converging on the same runtime structure.

### Method 1: JavaScript/TypeScript API

```typescript
import { mergeAutonomousConfig } from 'packages/coding-agent/src/core/agent-session-config';

const autonomousConfig = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['npm run lint', 'npm run test'],
    maxRetries: 2,
    timeoutMs: 15000
  },
  limits: {
    maxContinuations: 10,
    maxTurns: 50,
    maxTokens: 100_000,
    timeoutMs: 5 * 60_000
  }
});

```

### Method 2: CLI Flags

Parsed in `runtimeAutonomousConfigFromArgs` within [`packages/coding-agent/src/main.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/main.ts):

```bash
prime-agent \
  --autonomous \
  --autonomous-gates="npm run lint" \
  --autonomous-gates="pytest" \
  --autonomous-gate-retries=3 \
  --autonomous-gate-timeout=20000 \
  --autonomous-max-continuations=20 \
  --autonomous-max-turns=100 \
  --autonomous-timeout=600000

```

### Method 3: Runtime Slash Commands

Handled in [`packages/coding-agent/src/core/slash-commands.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/slash-commands.ts):

```typescript
// Enable autonomous mode
await session.prompt('/autonomous on');

// Check current configuration and limits
await session.prompt('/autonomous status');

// Disable autonomous mode
await session.prompt('/autonomous off');

```

## Practical Configuration Examples

### Example: Type-Safe Development with Retry

```typescript
import { mergeAutonomousConfig } from 'packages/coding-agent/src/core/agent-session-config';

const config = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['tsc --noEmit', 'npm run lint:fix -- --max-warnings=0'],
    maxRetries: 3,        // Allow 3 attempts to fix type/lint errors
    timeoutMs: 30000
  },
  limits: {
    maxContinuations: 15, // Hard stop after 15 continuation attempts
    maxTurns: 75
  }
});

```

### Example: Test-Driven Autonomous Development

```typescript
const tddConfig = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['npm test -- --watch=false --bail'],
    maxRetries: 5,        // Generous retries for iterative test fixing
    timeoutMs: 60000      // Longer timeout for test suites
  },
  limits: {
    maxContinuations: 25,
    maxTokens: 250_000    // Higher token budget for test generation
  }
});

```

### Example: Strict Mode (No Retries)

For safety-critical edits where any failure requires human review:

```typescript
const strictConfig = mergeAutonomousConfig(undefined, {
  enabled: true,
  gates: {
    commands: ['make verify'],  // Comprehensive verification
    maxRetries: 0,              // No auto-retry on failure
    timeoutMs: 120000
  },
  limits: {
    maxContinuations: 5,
    maxTurns: 20
  }
});

```

## Internal Runtime Flow

The autonomous execution loop in [`packages/coding-agent/src/core/autonomous.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/autonomous.ts) coordinates these components:

| Function | Purpose |
|----------|---------|
| `nextAutonomousContinuation` | Determines if another turn should run based on gates, limits, and retry state |
| `refreshAutonomousQualityGates` | Executes configured gate commands and evaluates exit codes |
| `addAutonomousContinuation` | Injects a new autonomous continuation into the session |
| `autonomousLimitReason` | Returns string reason when limits trigger stop (`"maxContinuations"`, `"retry_exhausted"`, etc.) |

Status display is handled in [`packages/coding-agent/src/modes/print-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/print-mode.ts), which renders current gate status, retry counts, and limit reasons in the TUI.

## Key Implementation Files

- **[`packages/coding-agent/src/core/autonomous.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/autonomous.ts)** — Core runtime state, gate execution, retry logic
- **[`packages/coding-agent/src/core/agent-session-config.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/agent-session-config.ts)** — Configuration merging and defaults
- **[`packages/coding-agent/src/main.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/main.ts)** — CLI argument parsing
- **[`packages/coding-agent/src/core/slash-commands.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/core/slash-commands.ts)** — `/autonomous` command handlers
- **[`packages/coding-agent/src/modes/print-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/print-mode.ts)** — TUI status display

## Summary

- **Quality gates** are shell commands configured via `autonomous.gates.commands` that validate each turn's output
- **Auto-retry** is enabled by setting `autonomous.gates.maxRetries > 0`, allowing re-execution when gates fail
- Retries only proceed when **workspace changes are detected**, preventing infinite loops on unfixable errors
- Configure via **JavaScript API**, **CLI flags**, or **runtime slash commands** depending on your workflow
- Combine `maxRetries` with `maxContinuations` and `maxTurns` to create reliable bounded autonomy

## Frequently Asked Questions

### What happens when all retries are exhausted?

When `gateAttempts[gateId]` reaches `maxRetries`, the runtime sets the limit reason to `"retry_exhausted"` and stops injecting autonomous continuations. The session remains active for manual interaction but will not auto-continue. You can inspect the final gate output to diagnose why recovery failed.

### Can different gates have different retry limits?

The current implementation in [`autonomous.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/autonomous.ts) applies a single `maxRetries` value to all gates in the `commands` array. Retry tracking is per-gate-ID, but the limit is shared. For asymmetric retry policies, wrap commands in external scripts that implement custom logic.

### How does Prime Agent detect workspace changes between retries?

Between retry attempts, the runtime compares workspace snapshots. If no changes occurred, the retry is not granted to prevent infinite loops. This check happens in `nextAutonomousContinuation` before calling `addAutonomousContinuation`.

### Do retries count against continuation and turn limits?

Retries consume **autonomous continuations** from `maxContinuations` but do **not** increment the turn counter until the retry budget is exhausted. This design allows iterative fixing without rapidly depleting the turn budget.