> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai "say hello" --autonomy auto_edit
```

<Frame>
  <img src="https://mintcdn.com/praisonai/SX0Y8_-DRBjzOTnt/docs/cli/autonomy-modes-auto-edit-mode-creates-files-a.gif?s=78d22a2ed31afaffbadf50bd35997902" alt="Auto edit mode creates files automatically" width="1497" height="1104" data-path="docs/cli/autonomy-modes-auto-edit-mode-creates-files-a.gif" />
</Frame>

## Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

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

## Python API

### Basic Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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:

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    CLI[CLI AutonomyMode] -->|to_sdk_level| SDK[SDK AutonomyLevel]
    CLI -->|FULL_AUTO| ENV[PRAISONAI_AUTO_APPROVE=true]
    ENV --> AR[SDK ApprovalRegistry]
    
    classDef cli fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef sdk fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef env fill:#10B981,stroke:#7C90A0,color:#fff
    
    class CLI cli
    class SDK,AR sdk
    class ENV env
```

* **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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.cli.features.autonomy_mode import AutonomyMode

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

## Environment Variables

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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](/docs/configuration/autonomy-config) - SDK autonomy configuration
* [Autonomy Concept](/docs/concepts/autonomy) - Architecture and design
* [Slash Commands](/docs/cli/slash-commands) - Interactive commands
* [Sandbox Execution](/docs/cli/sandbox-execution) - Isolated command execution
* [Git Integration](/docs/cli/git-integration) - Safe code changes with git