Permissions

HAPI provides granular control over AI agent permissions, allowing you to balance speed and safety based on your needs.

Overview

Every AI agent in HAPI can operate in different permission modes that control how much autonomy the agent has. From fully manual approval to complete automation, you decide the level of control.

Per-Agent Modes

Each agent type has its own set of permission modes

Real-Time Switching

Change modes mid-session without restarting

Approval Workflows

Get notified and approve/deny actions from any device

Safe Defaults

Default modes require approval for destructive actions

Permission Modes by Agent

Claude Code

Claude Code supports four permission modes:

Mode	Label	Description	Tone
`default`	Default	Standard approval workflow — requests permission for tool usage	Neutral
`acceptEdits`	Accept Edits	Auto-approves file edits but asks for other tools	Warning
`plan`	Plan Mode	Creates execution plans for review before running	Info
`bypassPermissions`	YOLO	Fully autonomous — no permission requests	Danger

Codex / Gemini

Codex and Gemini share the same modes:

Mode	Label	Description	Tone
`default`	Default	Standard approval workflow	Neutral
`read-only`	Read Only	Agent can only read files, no modifications	Warning
`safe-yolo`	Safe YOLO	Auto-approves safe operations, asks for risky ones	Warning
`yolo`	YOLO	Fully autonomous — no permission requests	Danger

OpenCode

OpenCode has simplified modes:

Mode	Label	Description	Tone
`default`	Default	Standard approval workflow	Neutral
`yolo`	YOLO	Fully autonomous — no permission requests	Danger

Cursor Agent

Cursor supports:

Mode	Label	Description	Tone
`default`	Default	Standard approval workflow	Neutral
`plan`	Plan Mode	Creates execution plans first	Info
`ask`	Ask Mode	Prompts before every action	Info
`yolo`	YOLO	Fully autonomous	Danger

The mode names come directly from each agent’s CLI. HAPI surfaces the same modes you’d use in the terminal.

Mode Descriptions

Default Mode

The balanced approach for most workflows:

✅ Agent requests permission for file edits
✅ Agent requests permission for bash commands
✅ Agent requests permission for other tools
⚠️ You approve/deny via web, PWA, or Telegram

Best for: Daily development, unfamiliar codebases, learning

Accept Edits (Claude Code)

Trust the agent with file changes:

✅ Auto-approves file edits (Write, Edit)
❌ Still asks for bash commands
❌ Still asks for other tools

Best for: Refactoring, when you trust the agent’s coding ability

Plan Mode (Claude Code, Cursor)

Review before execution:

📋 Agent creates execution plan
⏸️ Pauses for your review
✅ You approve the whole plan or iterate

Best for: Complex tasks, architecture changes, risky operations

Read-Only (Codex, Gemini)

Explore without risk:

✅ Agent can read files
✅ Agent can search codebase
❌ No file modifications
❌ No bash commands

Best for: Code review, analysis, exploration

Safe YOLO (Codex, Gemini)

Automation with guardrails:

✅ Auto-approves “safe” operations (reads, writes to existing files)
❌ Asks for risky operations (delete, network, installs)

Best for: Trusted codebases, routine tasks

YOLO Mode (All Agents)

Full autonomy:

✅ Auto-approves everything
✅ No interruptions
⚠️ Agent has full control

Best for: Trusted agents, sandboxed environments, quick iterations

YOLO mode grants full control to the AI. Use with caution, especially in production environments.

Approval Workflows

Permission Request Flow

1. AI agent requests tool permission (e.g., file edit)
         │
         ▼
2. CLI sends permission request to hub
         │
         ▼
3. Hub stores request and notifies via SSE + Telegram
         │
         ▼
4. User receives notification on phone
         │
         ▼
5. User approves/denies in web app or Telegram
         │
         ▼
6. Hub relays decision to CLI via Socket.IO
         │
         ▼
7. CLI informs AI agent, execution continues

Approval Channels

You can approve permissions from:

Web App

View details, approve, or deny

PWA

Get push notifications, respond instantly

Inline buttons in notifications

Permission Details

When reviewing a permission request, you see:

Tool name (e.g., “Write”, “Bash”, “Edit”)
Files affected (for file operations)
Command (for bash operations)
Context from the agent’s reasoning

Switching Modes

From Web Interface

Open Session

Navigate to the session in web app

Permission Mode Selector

Click the permission mode button (shows current mode)

Select Mode

Choose new mode from dropdown

Instant Switch

Mode changes immediately without restarting session

From API

curl -X POST https://your-hub/api/sessions/:id/permission-mode \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "yolo"}'

Via CLI

Start session with specific mode:

# Claude Code with YOLO mode
hapi --permission-mode yolo

# Codex in read-only mode
hapi codex --permission-mode read-only

# Cursor in plan mode
hapi cursor --permission-mode plan

Use Cases

Exploratory Phase

Start safe, then speed up:

Begin: Use default mode to understand codebase
Trust building: Switch to acceptEdits for refactoring
Rapid iteration: Switch to yolo for quick fixes

Production Hotfixes

Stay cautious:

Always use default or plan mode
Review every change carefully
Never use yolo in production

Bulk Refactoring

Balance speed and safety:

Use plan mode for architecture changes
Review the plan
Switch to acceptEdits for execution
Monitor progress

Learning

Understand agent behavior:

Use default mode
Review every permission request
Learn what the agent wants to do
Adjust mode as you build trust

Real-Time Notifications

When a permission is requested:

Push Notifications (PWA)

🔔 Permission Request

Claude Code needs approval
Edit 3 files in src/

[Tap to review]

Telegram Notifications

🔔 Permission Request

Session: my-project
Agent: Claude Code

Requests permission to edit files:
- src/index.ts
- src/utils.ts

[Approve] [Deny] [View Session]

In-App

Session shows:

Badge count of pending requests
Inline approval UI in chat
Highlighted permission requests

Permission Mode Types

From shared/src/modes.ts:

export const CLAUDE_PERMISSION_MODES = [
  'default', 'acceptEdits', 'bypassPermissions', 'plan'
] as const

export const CODEX_PERMISSION_MODES = [
  'default', 'read-only', 'safe-yolo', 'yolo'
] as const

export const GEMINI_PERMISSION_MODES = [
  'default', 'read-only', 'safe-yolo', 'yolo'
] as const

export const OPENCODE_PERMISSION_MODES = [
  'default', 'yolo'
] as const

export const CURSOR_PERMISSION_MODES = [
  'default', 'plan', 'ask', 'yolo'
] as const

Permission modes are validated at runtime using Zod schemas. Invalid modes are rejected.

Best Practices

Starting a New Project

Use default mode initially
Build trust with the agent over time
Graduate to acceptEdits after confidence
Reserve yolo for routine tasks

Working with Sensitive Code

Always use default or plan mode
Review every change
Consider read-only for analysis
Never use yolo in production

Rapid Prototyping

Start with yolo for speed
Review changes in git diffs
Switch to stricter mode for refinement
Commit often

Team Environments

Establish team conventions
Document which modes to use when
Default to safer modes for junior devs
Use plan mode for shared codebases

Security Considerations

Sandboxing

HAPI does not sandbox agent actions:

Agent runs with your user permissions
Has access to all files you can access
Can run any command you can run
No containerization or virtualization

Agents have the same permissions as you. Treat yolo mode like giving someone your terminal.

Recommended Setup

For safer operation:

Separate machine: Run agents on non-production machine
Docker container: Run CLI in container for isolation
Limited user: Run CLI as user with restricted permissions
Git: Always use version control to review changes

Remote Control

Approve permissions from anywhere

Get notified and approve via Telegram

PWA

Push notifications for permission requests

Get Started

Core Concepts

Features

Agents

Deployment

Advanced

Resources

​Overview

Per-Agent Modes

Real-Time Switching

Approval Workflows

Safe Defaults

​Permission Modes by Agent

​Claude Code

​Codex / Gemini

​OpenCode

​Cursor Agent

​Mode Descriptions

​Default Mode

​Accept Edits (Claude Code)

​Plan Mode (Claude Code, Cursor)

​Read-Only (Codex, Gemini)

​Safe YOLO (Codex, Gemini)

​YOLO Mode (All Agents)

​Approval Workflows

​Permission Request Flow

​Approval Channels

Web App

PWA

Telegram

​Permission Details

​Switching Modes

​From Web Interface

​From API

​Via CLI

​Use Cases

​Exploratory Phase

​Production Hotfixes

​Bulk Refactoring

​Learning

​Real-Time Notifications

​Push Notifications (PWA)

​Telegram Notifications

​In-App

​Permission Mode Types

​Best Practices

​Security Considerations

​Sandboxing

​Recommended Setup

​Related Features

Remote Control

Telegram

PWA

Build docs developers (and LLMs) love

Overview

Permission Modes by Agent

Claude Code

Codex / Gemini

OpenCode

Cursor Agent

Mode Descriptions

Default Mode

Accept Edits (Claude Code)

Plan Mode (Claude Code, Cursor)

Read-Only (Codex, Gemini)

Safe YOLO (Codex, Gemini)

YOLO Mode (All Agents)

Approval Workflows

Permission Request Flow

Approval Channels

Permission Details

Switching Modes

From Web Interface

From API

Via CLI

Use Cases

Exploratory Phase

Production Hotfixes

Bulk Refactoring

Learning

Real-Time Notifications

Push Notifications (PWA)

Telegram Notifications

In-App

Permission Mode Types

Best Practices

Security Considerations

Sandboxing

Recommended Setup

Related Features