How to Configure Autonomous Mode with Turn, Token, and Time Budgets in Prime Agent

Prime Agent's autonomous mode supports three independent budgets—turns, tokens, and time—that you can configure via CLI flags or the /autonomous slash command to control how long the agent runs without user intervention.

Autonomous mode in Prime Agent lets the coding agent continue generating tool calls and responses without pausing for user input. To prevent runaway execution, the runtime enforces three configurable limits tracked in AgentAutonomousState and validated through the checkAutonomousLimits helper in packages/coding-agent/src/core/autonomous.ts.

Understanding the Three Budget Types

Each budget operates independently and stops autonomous execution when exceeded:

Budget	Description	Default Value	Purpose
Turns	Number of assistant replies (each may include tool calls)	12	Limits conversation depth
Tokens	Total token consumption across the autonomous segment	100,000	Controls API cost and context window usage
Time	Wall-clock milliseconds before forced termination	1,800,000 ms (30 min)	Prevents indefinite hanging

When any limit triggers, Prime Agent injects a stop message like maxTurns reached (12/12) and returns to normal interactive mode.

Configuration Methods

You can set autonomous mode budgets through three interfaces: CLI flags, slash commands, or programmatic session configuration.

CLI Flag Configuration

Launch Prime Agent with custom budgets using flags parsed in packages/coding-agent/src/main.ts:

prime-agent --autonomous on \
            --autonomous-max-turns 30 \
            --autonomous-max-tokens 300000 \
            --autonomous-timeout-ms 900000

Flag reference for packages/coding-agent/src/main.ts:

Flag	Maps to	Unit
--autonomous-max-turns	maxTurns	Integer count
--autonomous-max-tokens	maxTokens	Integer tokens
--autonomous-timeout-ms	timeoutMs	Milliseconds

Slash Command Configuration

From within a session, use the /autonomous command registered in packages/coding-agent/src/cli.ts:

/autonomous on maxTurns=20 maxTokens=250000 timeoutMs=600000

Additional slash commands:

• /autonomous on — Enable with defaults
• /autonomous off — Disable immediately
• /autonomous status — View current usage against limits

The status response format from packages/coding-agent/src/core/agent-session.ts shows:

Autonomous mode: enabled. Continuations: 0/1. Turns: 3/25. Tokens: 12,342/200,000.

Programmatic Configuration

For custom scripts or extensions, pass budget values through the AgentSession constructor or prompt() method:

import { AgentSession } from "packages/coding-agent/src/core/agent-session";

const session = new AgentSession({
  autonomous: {
    enabled: true,
    maxTurns: 25,
    maxTokens: 200_000,
    timeoutMs: 5 * 60_000, // 5 minutes
  },
});

// Or via prompt():
await session.prompt("/autonomous on", {
  autonomous: {
    enabled: true,
    maxTurns: 15,
    maxTokens: 150_000,
    timeoutMs: 300_000,
  },
});

How Limits Are Enforced

The enforcement logic resides in two core files according to the Prime Agent source code:

Budget Tracking — packages/coding-agent/src/core/autonomous.ts

Defines AgentAutonomousConfig interface and implements checkAutonomousLimits():

// Simplified structure based on source analysis
interface AgentAutonomousConfig {
  enabled: boolean;
  maxTurns: number;      // default: 12
  maxTokens: number;     // default: 100000
  timeoutMs: number;     // default: 1800000
}

interface AgentAutonomousState {
  turnCount: number;
  tokenCount: number;
  startTime: number;
}

After each assistant turn, checkAutonomousLimits() validates cumulative usage against configured ceilings.

Status and Termination — packages/coding-agent/src/core/agent-session.ts

• Builds human-readable status strings for /autonomous status
• Injects formatted stop messages when limits breach
• Handles the /autonomous command dispatch

Important Behavioral Details

Failed tool calls do not count toward the turn limit, but aborted assistant messages do count. This distinction is validated by the test case it("counts aborted assistant messages against autonomous usage limits") in the test suite.

Budget counters are cumulative within a single autonomous block. If the user interrupts the block (new command, manual /autonomous off), counters reset for the next autonomous activation.

Recommended Budget Starting Points

Use Case	Turns	Tokens	Timeout
Quick code exploration	8-12	50,000	10 min (600,000 ms)
Feature implementation	20-30	200,000-300,000	30-60 min
Long-running refactors	50+	500,000+	2+ hours

Start conservative and increase based on observed consumption patterns from /autonomous status outputs.

Summary

• Three independent budgets control autonomous execution: turns (maxTurns), tokens (maxTokens), and time (timeoutMs)
• Configure via CLI flags (--autonomous-max-*), slash commands (/autonomous on maxTurns=N), or programmatic API
• Defaults are 12 turns, 100,000 tokens, and 30 minutes — adjust based on task complexity
• Enforcement happens in packages/coding-agent/src/core/autonomous.ts, with status reporting in packages/coding-agent/src/core/agent-session.ts
• Aborted messages count toward limits; failed tool calls do not

Frequently Asked Questions

What happens when an autonomous budget is exceeded?

Prime Agent immediately injects a stop message (e.g., maxTurns reached (12/12)) and terminates the autonomous segment, returning control to the user for the next input.

Can I change budgets mid-session without restarting?

Yes. Use /autonomous on maxTurns=N maxTokens=M timeoutMs=T to reconfigure, or call session.prompt() with new autonomous options. New settings apply to the next autonomous block.

Why do my token counts differ from API billing?

The maxTokens budget tracks tokens consumed during the autonomous segment only, excluding system prompts and prior conversation history outside the block. It approximates but may not match exact provider billing.

How do I disable autonomous mode entirely?

Run /autonomous off in the TUI, omit --autonomous on from CLI startup, or set { autonomous: { enabled: false } } in programmatic configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}