Autonomy Modes

Arcana uses progressive autonomy — you control how much the agent can do without asking. Start safe, increase capability as you gain confidence.

The Five Modes

Observe Mode

Read-only analysis. The agent can read files, search code, and analyze your project but cannot make any changes or suggestions.

# Set observe mode
export ARCANA_AUTONOMY=observe

# Or in the TUI:
/mode observe

# Usage: safe analysis of unfamiliar codebases
arcana run "explain the architecture of this codebase"
arcana run "find all security-sensitive code paths"

Advise Mode

The agent can suggest changes but cannot execute them. Good for code review and planning.

# Set advise mode
export ARCANA_AUTONOMY=advise

# Usage: get recommendations without risk
arcana run "suggest improvements to the error handling"
arcana run "plan a refactor of the database layer"

Ask Mode (Default)

The agent asks before executing any tool call. This is the default and recommended mode for most users.

# Default mode — no configuration needed
arcana

# The agent will ask:
# "I'd like to run: git add .
# Should I proceed? [y/n]"

Enforce Mode

The agent executes without asking. Use only when you trust the agent's judgment completely.

# Set enforce mode
export ARCANA_AUTONOMY=enforce

# Usage: automated workflows where speed matters
arcana run "fix all linting errors in src/"
arcana run "refactor utils.js to TypeScript"

Locked Mode

Minimal permissions. The agent can only read files and cannot execute tools, suggest changes, or modify anything.

# Set locked mode
export ARCANA_AUTONOMY=locked

# Usage: when you only need answers, not actions
arcana run "what does this function do?"
arcana run "explain this error message"

Switching Modes

# Environment variable (affects new sessions)
export ARCANA_AUTONOMY=advise

# TUI slash command (affects current session)
/mode observe
/mode advise
/mode ask
/mode enforce

# Config file (persistent default)
# ~/.arcana/config.json
{
  "autonomy": "ask"
}

Per-Tool Permissions

Even in Ask or Enforce mode, you can restrict specific tools:

# In the TUI, you can allow/deny individual tools:
/allow shell      # Allow shell commands
/deny filesystem  # Deny file writes

# Or configure in config.json:
{
  "tools": {
    "shell": { "enabled": true },
    "filesystem": { "enabled": true, "write": false },
    "git": { "enabled": true }
  }
}

Mode Recommendations