Tools & Permissions

OWL provides two layers of control over what it can do:

1. Tool Profiles - Which tools are available (minimal, coding, full)
2. Permission Modes - When to ask before acting (default, auto-edit, plan, yolo)

---

Permission Modes

Control when OWL asks for permission. Toggle with /mode or cycle through modes.

Safe Mode (Default)

Ask before file edits and shell commands.

/mode safe

Action	Behavior
Read files	Allowed
Write/Edit files	Ask permission
Delete files	Ask permission
Shell commands	Ask permission

Auto Mode

Allow file changes, still ask for shell commands.

/mode auto

Action	Behavior
Read files	Allowed
Write/Edit files	Allowed
Delete files	Allowed
Shell commands	Ask permission

Plan Mode

Read-only mode for planning before execution.

/mode plan

Action	Behavior
Read files	Allowed
Write/Edit files	Blocked
Delete files	Blocked
Shell commands	Blocked

Use this when you want OWL to analyze and plan without making any changes.

YOLO Mode

Allow everything without asking. Use with caution.

/mode yolo

Action	Behavior
All actions	Allowed

Safety: Even in YOLO mode, dangerous commands like rm -rf / still require confirmation.

Checking Current Mode

/mode

The status bar also shows the current mode indicator.

---

Tool Profiles

Minimal (Read-Only)

Safe exploration mode - OWL can only read, not modify.

/tools minimal

Available Tools:

Tool	Description
list_files	List directory contents
read_file	Read file contents
search_files	Search for patterns
ask_user	Ask clarifying questions
analyze_image	Analyze images (OCR, descriptions)

Use Cases:

• Exploring unfamiliar codebases
• Code review and analysis
• Security-sensitive environments
• Learning about a project

Coding (Default)

Full development mode - read, write, and execute commands.

/tools coding

Available Tools:

Tool	Description
list_files	List directory contents
read_file	Read file contents
write_file	Create/write files
edit_file	Modify existing files
delete_file	Delete files or empty directories
search_files	Search for patterns
run_command	Execute shell commands (git, npm, python, etc.)
ask_user	Ask clarifying questions
analyze_image	Analyze images (OCR, descriptions)

Use Cases:

• Active development
• Running tests and builds
• Git operations
• Package management
• Implementing features

Full (Reserved)

Currently identical to Coding. Reserved for future extensions.

/tools full

Available Tools: Same as Coding profile.

Future Plans: May include additional tools like web browsing, API calls, or system integrations.

Tool Details

list_files

List files and directories:

Parameters:
  path: Directory to list (required)
  pattern: Glob pattern to filter (optional)
  recursive: Search subdirectories (optional)

Example:

you: What Python files are in src?

● List(src)
  ⎿  5 items

owl: Found 5 Python files:
- main.py
- utils.py
...

read_file

Read file contents:

Parameters:
  path: File to read (required)
  start_line: Start line number (optional)
  end_line: End line number (optional)

Limits:

• Max file size: 1MB
• Line numbers are 1-indexed

write_file

Create or overwrite a file:

Parameters:
  path: File path (required)
  content: Content to write (required)

Safety:

• Only writes to home directory or /tmp
• Creates parent directories if needed

edit_file

Replace text in a file:

Parameters:
  path: File to edit (required)
  old_text: Text to find (required)
  new_text: Replacement text (required)
  occurrence: Which occurrence (default: 1, 0=all)

search_files

Search for patterns:

Parameters:
  path: Directory to search (required)
  pattern: Search pattern (required)
  file_pattern: Glob for file types (default: *.py)

delete_file

Delete a file or empty directory:

Parameters:
  path: File or directory to delete (required)

Safety:

• Only deletes within home directory or /tmp
• Cannot delete critical paths (.ssh, .config, .bashrc, .zshrc)
• Cannot delete non-empty directories

run_command

Execute shell commands (Full profile only):

Parameters:
  command: Shell command (required)
  working_dir: Directory to run in (optional)

ask_user

Ask clarifying questions:

Parameters:
  question: Question text (required)
  options: List of choices (optional)

Always available in all profiles.

analyze_image

Analyze images for text extraction or visual understanding:

Parameters:
  prompt: What to analyze or extract (required)

Examples:

• "Extract all text from this screenshot"
• "Describe the layout of this UI"
• "What error message is shown?"

Requires a vision-capable model (e.g., moondream, llava).

Tool Output

OWL displays tool execution in a clean, informative format:

Running

◐ Bash(npm run build)

Completed

● Read(main.py)
  ⎿  42 lines

● Read 3 files
  ⎿  config.py, utils.py, helpers.py

● Edit(owl/tools/file_ops.py)
  ⎿  Added 5 lines, removed 2

● Bash(npm run build)
  ⎿  Exit 0

● Delete(dummy.md)
  ⎿  Deleted

✻ 4.2s

Features

• Grouped reads: Consecutive file reads are collapsed into one line
• Edit summary: Shows lines added/removed, not just "replaced"
• Elapsed time: Shows how long the response took

Failed

● Bash(invalid-command)
  ⎿  Command not found

Output Modes

Toggle between summary and detailed output:

/tools collapsed    # Summary only (default)
/tools expanded     # Full details with arguments

Checking Current Profile

/tools

Output:

Tool Profile: coding
Output Mode: collapsed

Available Tools:
  - list_files
  - read_file
  - write_file
  - edit_file
  - search_files
  - ask_user

Set profile: /tools minimal|coding|full
Set output: /tools collapsed|expanded

Safety Considerations

File Operations

• Write operations restricted to ~ and /tmp
• Cannot write to system directories
• Cannot overwrite without explicit action

Shell Commands

Available in Coding and Full profiles. Shell commands can:

• Modify system state
• Access network
• Run arbitrary code

Use /mode safe to require confirmation for each command.

When to Use Each Profile

Situation	Profile
Exploring new code	minimal
Active development	coding
Running tests	coding
Security audit	minimal
Build/deploy	coding
Code review	minimal
Read-only investigation	minimal

Profile Persistence

Profile setting persists for the daemon session:

/tools coding  # Set once

# All subsequent operations use coding profile
# Until daemon restart or profile change

Tool Execution Flow

1. OWL decides to use a tool
2. Profile check - is tool available?
3. If yes, execute and show result
4. If no, inform user of limitation

# In minimal mode:
you: Create a new file called test.py

owl: I can't create files in minimal mode.
Would you like to switch to coding mode?
Use: /tools coding