Autonomy Modes

Control how much autonomy the AI has when making changes

Autonomy Modes

PraisonAI CLI supports different autonomy levels that control how much freedom the AI has when making changes to your code. Inspired by Codex CLI’s approval modes, this feature lets you balance speed with safety.

Overview

Autonomy modes determine whether the AI needs your approval before taking actions like editing files or running commands.

Mode	Description	Best For
suggest	Requires approval for all changes	Learning, sensitive code
auto_edit	Auto-approves file edits, asks for commands	Normal development
full_auto	Auto-approves everything	Trusted tasks, automation

Quick Start

praisonai "say hello" --autonomy auto_edit

Usage

# Default mode (suggest)
praisonai "Fix the bug in main.py"

# Auto-edit mode
praisonai "Refactor the auth module" --autonomy auto_edit

# Full auto mode (use with caution!)
praisonai "Update all imports" --autonomy full_auto

Modes Explained

Suggest Mode (Default)

The safest mode. Every action requires your explicit approval.

praisonai "Add error handling to api.py" --autonomy suggest

Behavior:

• ✅ File reads - Auto-approved
• ❓ File writes - Requires approval
• ❓ Shell commands - Requires approval
• ❓ File deletions - Requires approval

Example interaction:

AI wants to edit: src/api.py
+    try:
+        response = fetch_data()
+    except Exception as e:
+        logger.error(f"Failed: {e}")

[A]pprove / [R]eject / [E]dit? _

Auto-Edit Mode

Balanced mode for normal development. File edits are auto-approved, but shell commands still require approval.

praisonai "Refactor the database module" --autonomy auto_edit

Behavior:

• ✅ File reads - Auto-approved
• ✅ File writes - Auto-approved
• ❓ Shell commands - Requires approval
• ❓ File deletions - Requires approval

Full Auto Mode

Maximum speed, minimum interruption. Use only for trusted tasks.

praisonai "Update copyright headers in all files" --autonomy full_auto

Behavior:

• ✅ File reads - Auto-approved
• ✅ File writes - Auto-approved
• ✅ Shell commands - Auto-approved
• ✅ File deletions - Auto-approved

Full auto mode can make destructive changes without asking. Always review the task carefully before using this mode.

Python API

Basic Usage

from praisonai.cli.features import AutonomyModeHandler

# Initialize with a mode
handler = AutonomyModeHandler()
handler.initialize(mode="auto_edit")

# Check current mode
print(handler.get_mode())  # "auto_edit"

# Change mode
handler.set_mode("suggest")

Requesting Approval

from praisonai.cli.features.autonomy_mode import (
    AutonomyModeHandler,
    ActionRequest,
    ActionType
)

handler = AutonomyModeHandler()
handler.initialize(mode="suggest")

# Create an action request
action = ActionRequest(
    action_type=ActionType.FILE_WRITE,
    description="Edit src/main.py to add logging",
    details={"file": "src/main.py", "changes": "+import logging"}
)

# Request approval
result = handler.request_approval(action)

if result.approved:
    # Proceed with the action
    print("Action approved!")
else:
    print(f"Action rejected: {result.reason}")

Custom Approval Callback

def my_approval_callback(action):
    """Custom approval logic."""
    # Auto-approve test files
    if "test" in action.description.lower():
        return ApprovalResult(approved=True)
    
    # Ask user for everything else
    response = input(f"Approve '{action.description}'? [y/n]: ")
    return ApprovalResult(
        approved=response.lower() == 'y',
        reason="User decision"
    )

handler = AutonomyModeHandler()
handler.initialize(
    mode="suggest",
    approval_callback=my_approval_callback
)

The interactive CLI populates this same reason field automatically: rejecting a tool call in the Rich prompt or Textual TUI captures your one-line reason and returns it to the agent. See Reject with a Reason.

Action Types

The system recognizes different types of actions:

Action Type	Description	Risk Level
FILE_READ	Reading file contents	Low
FILE_WRITE	Creating or modifying files	Medium
FILE_DELETE	Deleting files	High
SHELL_COMMAND	Running shell commands	High
NETWORK_REQUEST	Making HTTP requests	Medium
GIT_OPERATION	Git commands	Medium
INSTALL_PACKAGE	Installing dependencies	High
SYSTEM_CHANGE	System-level changes	Critical

Approval Policies

Each mode has a policy that defines what’s auto-approved:

from praisonai.cli.features.autonomy_mode import AutonomyPolicy, AutonomyMode

# Get policy for a mode
policy = AutonomyPolicy.for_mode(AutonomyMode.AUTO_EDIT)

print(policy.auto_approve)  # {ActionType.FILE_READ, ActionType.FILE_WRITE}
print(policy.require_approval)  # {ActionType.SHELL_COMMAND, ...}

Custom Policies

Create custom policies for specific needs:

from praisonai.cli.features.autonomy_mode import AutonomyPolicy, ActionType

custom_policy = AutonomyPolicy(
    mode=AutonomyMode.SUGGEST,
    auto_approve={ActionType.FILE_READ},
    require_approval={
        ActionType.FILE_WRITE,
        ActionType.SHELL_COMMAND
    },
    blocked={ActionType.FILE_DELETE}  # Never allow
)

handler.initialize(mode="suggest", policy=custom_policy)

Remembered Decisions

The autonomy manager can remember your decisions for similar actions:

handler = AutonomyModeHandler()
manager = handler.initialize(mode="suggest")

# First time - asks for approval
action1 = ActionRequest(ActionType.FILE_WRITE, "Edit config.py")
result1 = manager.request_approval(action1)  # User approves

# If user chose "Always approve this type"
# Second time - auto-approved based on remembered decision
action2 = ActionRequest(ActionType.FILE_WRITE, "Edit utils.py")
result2 = manager.request_approval(action2)  # Auto-approved

Statistics

Track approval statistics:

stats = handler.get_stats()

print(f"Total actions: {stats['total_actions']}")
print(f"Auto-approved: {stats['auto_approved']}")
print(f"User approved: {stats['user_approved']}")
print(f"Rejected: {stats['rejected']}")

Best Practices

When to Use Each Mode

Scenario	Recommended Mode
Learning PraisonAI	suggest
Production code	suggest or auto_edit
Refactoring	auto_edit
Bulk updates	full_auto (with review)
CI/CD automation	full_auto
Sensitive files	suggest

Safety Tips

1. Start with suggest mode - Get familiar with what the AI does
2. Review full_auto tasks - Read the task description carefully
3. Use git - Always have uncommitted changes backed up
4. Set blocked actions - Prevent dangerous operations
5. Monitor statistics - Track what’s being auto-approved

SDK Bridge

The CLI autonomy system bridges to the Core SDK’s approval and autonomy systems:

• DRY enum values: CLI AutonomyMode derives values from SDK AutonomyLevel (single source of truth)
• Approval bridging: AutonomyManager.set_mode(FULL_AUTO) sets PRAISONAI_AUTO_APPROVE=true so SDK tools auto-approve
• Conversion: Use mode.to_sdk_level() to convert CLI mode to SDK enum

Since PR #4878, the FULL_AUTO → PRAISONAI_AUTO_APPROVE=true → ApprovalRegistry bridge works reliably for CLI sessions too. CLI sessions install InteractiveCLIApprovalBackend, and before #4878 that attached backend skipped the env-var check and prompted anyway; now the env var is honoured on the attached-backend path. See Standing grants and attached backends.

from praisonai.cli.features.autonomy_mode import AutonomyMode

mode = AutonomyMode.AUTO_EDIT
sdk_level = mode.to_sdk_level()  # Returns AutonomyLevel.AUTO_EDIT

Environment Variables

# Set default autonomy mode
export PRAISONAI_AUTONOMY_MODE=auto_edit

# Disable full_auto mode entirely
export PRAISONAI_DISABLE_FULL_AUTO=true

# SDK auto-approve (set automatically by CLI when FULL_AUTO)
export PRAISONAI_AUTO_APPROVE=true

Related Features

• AutonomyConfig - SDK autonomy configuration
• Autonomy Concept - Architecture and design
• Slash Commands - Interactive commands
• Sandbox Execution - Isolated command execution
• Git Integration - Safe code changes with git