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
- ✅ 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
- ✅ 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
- ✅ 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
)
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
- Start with suggest mode - Get familiar with what the AI does
- Review full_auto tasks - Read the task description carefully
- Use git - Always have uncommitted changes backed up
- Set blocked actions - Prevent dangerous operations
- Monitor statistics - Track what’s being auto-approved
Environment Variables
# Set default autonomy mode
export PRAISONAI_AUTONOMY_MODE=auto_edit
# Disable full_auto mode entirely
export PRAISONAI_DISABLE_FULL_AUTO=true
