Permission Modes

Controls whether CodeBuddy should stop and ask before editing files, running commands, or making network requests. The mode determines the pace of the entire session: conservative modes require approval step by step, while more permissive modes let CodeBuddy continue for longer without interruption and report back at the end. Use strict modes for sensitive operations, and permissive modes when you trust the direction.

Available Modes

CodeBuddy Code provides the following permission modes. The first four are directly exposed to CLI users; the rest are for IDE integrations and subagent scenarios.

Modes You Can Switch Manually

Mode	What can run without asking	Use case
default	Read tool inside trusted directories	Default; suitable for sensitive work / getting started
acceptEdits	Read + Edit-family tools inside trusted directories	Keep writing, then review with git diff
plan	Delegates to the mode active before entering plan (default = default); additionally allows writing session plan files	Explore the code before deciding what to change
bypassPermissions	All tools, without asking	Use only in sandbox containers / VMs / offline dev containers
delegate	Coordination tools only (such as Agent / TaskCreate / SendMessage / team management); implementation tools are blocked	The main agent only decomposes and delegates work to subagents

Programmatic / Integration Modes (Not in the Shift+Tab Cycle)

Mode	When it appears
fullAccess	Passed by an IDE client through the protocol; semantically equivalent to globally allowing everything like bypassPermissions
work	Passed by an IDE client. Read is allowed directly (without checking trusted directories), Edit always asks, Bash allows only safe commands directly, and other tools ask
ignore	Only takes effect for subagents / teammates. It means “use the main session’s mode; do not let the subagent’s own frontmatter override it”. Main sessions do not use it

Switching Permission Modes

You do not switch modes by telling CodeBuddy in chat. Set them through the following three entry points instead.

Switch During a Session: Shift+Tab

In the CLI, press Shift+Tab to cycle through the following five modes:

default → bypassPermissions → acceptEdits → plan → delegate → default → ...

After switching, the current mode is shown in the lower-left status bar:

Mode	Status bar text	Color
default	Not shown	—
bypassPermissions	⏵⏵ bypass permissions on (shift+tab to cycle)	warning
acceptEdits	⏵⏵ accept edits on (shift+tab to cycle)	info
plan	⏸ plan mode on (shift+tab to cycle)	planMode
plan + pre-mode	⏸ plan + accept edits (shift+tab to cycle) and similar	planMode
delegate	⇢ delegate mode on (shift+tab to cycle)	delegateMode

Specify at Startup: --permission-mode

codebuddy --permission-mode plan
codebuddy --permission-mode acceptEdits
codebuddy --permission-mode bypassPermissions
codebuddy --permission-mode default

The CLI option --permission-mode accepts only these four literals. Other modes (delegate / work / fullAccess / ignore) cannot be passed on the command line.

It also works under -p (headless mode):

codebuddy -p --permission-mode acceptEdits "refactor src/utils/foo.ts"

You can also add the following at startup:

• -y / --dangerously-skip-permissions: equivalent to --permission-mode bypassPermissions; skips all permission checks

Persistent Default: defaultMode

Write it to ~/.codebuddy/settings.json or repository .codebuddy/settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

If --permission-mode is also provided at startup, the CLI argument takes precedence. The fallback order is: current session value → permissions.defaultMode → default.

Automatic Memory of the “Pre-Plan Mode”

When entering plan, CodeBuddy remembers the current mode and restores it when leaving plan. This means:

• If you press Shift+Tab from acceptEdits into plan, the approval strategy for Read/Edit/Bash during plan still follows acceptEdits rules (except for the plan file, which never asks)
• When leaving plan, you return to acceptEdits; it will not be forcibly dropped to default

Detailed Semantics by Mode

default (Default)

A step-by-step approval mode. This is the safe option for beginners and for sensitive work.

Tool type	Decision
Read	Path is inside a trusted directory (cwd + permissions.additionalDirectories + user-added addDir) → allow; otherwise ask
Edit	Always ask
Bash	Always ask
Other	Always ask

acceptEdits (Auto-Approve File Edits)

Suitable when you want to keep writing and review the diff later, without being interrupted by every Edit approval prompt.

Tool type	Decision
Read	Inside trusted directories → allow; otherwise ask
Edit	Always allow
Bash	Always ask
Other	Always ask

Notes:

• Only Edit-family tools are auto-approved (Edit / Write / NotebookEdit, etc.). This does not affect Bash — Bash always follows a separate safety classification
• “Trusted directories” are based on the workspace root + user-configured permissions.additionalDirectories + startup --add-dir
• Writes to protected files still ask according to the original mode and do not use automatic allow

plan (Explore Before Changing)

In plan mode, CodeBuddy focuses on reading code and running read-only Bash commands to investigate, writes the proposal as a plan, and then comes back for your approval. It does not apply changes to your source code.

Plan mode is not an independent “fully read-only block”; it delegates to the pre-plan mode:

• Read: delegates the decision to the pre-plan mode (default is default)
• Edit: only allowed when the target path is the current session’s plan file; otherwise delegates to the pre-plan mode
• Bash: delegates to the pre-plan mode
• Enter plan through Shift+Tab or the EnterPlanMode tool; exit through another Shift+Tab or ExitPlanMode

Start directly in plan mode:

codebuddy --permission-mode plan

bypassPermissions (Skip All Checks)

Literally: skip all approvals. All Bash, Edit, network, and MCP operations execute immediately. Use only in the following scenarios:

• Isolated containers / VMs / dev containers
• Sandboxes with no external network access
• Scripted scenarios where you fully understand the consequences

Startup methods:

codebuddy --permission-mode bypassPermissions
# Equivalent
codebuddy -y
codebuddy --dangerously-skip-permissions

Disable Channel (Administrators)

Write permissions.disableBypassPermissionsMode: "disable" to settings at any layer:

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}

After this is written, even if the session switches to bypassPermissions, the permission strategy will fall back to default decisions. It takes effect when any layer of settings (user / project / local / CLI startup flag) is set to "disable".

delegate (Multi-Agent Coordination Mode)

In delegate mode, the main agent can only coordinate: assign tasks, start subagents, and communicate across members. It does not edit files or run commands itself.

Behavior:

• Only coordination tools (Agent / TaskCreate / SendMessage, etc.) remain in the main agent’s tool set, all allowed automatically
• Implementation tools (Read / Write / Edit / Bash, etc.) are blocked, and execution is delegated to subagents

This is suitable when you explicitly want the main agent to “plan only, with specialized subagents doing the implementation” (Agent Teams / Subagents).

Press Shift+Tab until delegate appears to enter it.

work (IDE Integration)

Set by the IDE client through the protocol; not directly exposed to CLI users. Semantics:

Tool type	Decision
Read	Allow directly (does not check trusted directories)
Edit	Always ask
Bash	Safe commands are allowed directly; risky ones ask
Other	Allow

fullAccess (IDE Integration)

Only passed through the IDE client protocol; same semantics as bypassPermissions.

ignore (Subagent Only)

Only used by subagent frontmatter / options. When a subagent writes permissionMode: ignore in its metadata, it is treated as “do not override the parent agent’s mode” and continues using the parent session’s current mode. This value does not appear in main sessions.

Protected Critical Files

Write operations to the following paths retain special handling even under acceptEdits / bypassPermissions:

• Repository itself: .git, .gitconfig, .gitmodules
• Shell config: .bashrc / .bash_profile / .zshrc / .zprofile / .envrc, etc.
• Package management: .npmrc / .yarnrc / .pnpmfile.cjs / bunfig.toml, etc.
• IDE / tools: .vscode / .idea / .husky / .devcontainer / .cargo / .yarn / .mvn
• CodeBuddy itself: .codebuddy (except .codebuddy/worktrees)
• MCP / config: .mcp.json / .codebuddy.json

Permission Mode Inheritance for Subagents

Subagents (Agent tool calls and Agent Teams members) inherit the main session’s permission mode by default. To force an override at the team / project layer:

{
  "permissions": {
    "subagentPermissionMode": "bypassPermissions"
  }
}

After this is written, all subagents run under bypassPermissions. Notes:

• Passing the mode parameter explicitly in an Agent tool call → highest priority, overrides this setting
• Writing permissionMode: ignore in subagent frontmatter → still runs under the main session mode (not affected by this setting)

Working with Permission Rules

Permission modes define the “baseline”. You can layer additional rules under permissions in ~/.codebuddy/settings.json or repository .codebuddy/settings.json:

{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test)", "Read(/etc/hosts)"],
    "ask": ["WebFetch"],
    "deny": ["Bash(rm -rf *)", "Edit(.git/**)"]
  }
}

• The allow / ask / deny layers have higher priority than mode decisions (except that bypassPermissions skips the entire permission layer)
• For detailed rule syntax, see Settings, Security, and IAM

Related Resources

• Agent Teams: Multi-Agent Collaboration: let the main agent focus on coordination in delegate mode
• Subagents: subagent tools and permission mode inheritance
• Hooks: use PreToolUse hooks for custom allow / block behavior
• Bash sandboxing: add filesystem / network isolation at the Bash command layer
• Settings: complete fields for permission rules, trusted directories, disableBypassPermissionsMode, and more
• CLI reference: startup parameters such as --permission-mode / -y / --add-dir
• Headless mode: use permission modes under the -p flow