From 8073317150428d220c57649df661329d7da37a73 Mon Sep 17 00:00:00 2001 From: Alexandre <44178713+alexbelgium@users.noreply.github.com> Date: Wed, 15 Jul 2026 10:09:44 +0200 Subject: [PATCH] Document Claude permission modes --- claude_desktop/README.md | 43 +++++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/claude_desktop/README.md b/claude_desktop/README.md index 09e9d22eae..33cf4208e7 100644 --- a/claude_desktop/README.md +++ b/claude_desktop/README.md @@ -24,15 +24,17 @@ currently does not include Computer Use or dictation. Everything is built around the Claude Desktop app. Claude Code is installed in the same image but is not exposed as a standalone service: Claude Desktop's cowork and dispatch sessions run it internally, and they pick up the shared -Claude Code configuration (`~/.claude`), hooks, MCP servers, and PATH tools. +Claude Code configuration (`~/.claude`), hooks, MCP servers, permissions, and +PATH tools. - **Claude Desktop** uses Headroom through its MCP tools. -- **Claude Code sessions inside Desktop** get the same MCP servers and the - RTK/TokenSave hooks through the shared Claude Code configuration. +- **Claude Code sessions inside Desktop** get the same MCP servers, permission + mode, and RTK/TokenSave hooks through the shared Claude Code configuration. - PATH-based Claude Code launches are routed through the supervised Headroom proxy when `headroom_wrap_claude_code` is enabled. If a Desktop release calls `/usr/bin/claude` directly, the session remains functional and still has the - Headroom MCP tools, but transparent proxy compression cannot be injected. + shared permission mode and Headroom MCP tools, but transparent proxy + compression cannot be injected. - **gnome-keyring** provides the Secret Service backend Electron needs to persist sign-in and dispatch permission grants across restarts. @@ -59,6 +61,8 @@ Git synchronization hooks. A repository is indexed only when it is listed in - Persistent `$HOME` at the configured `data_location` (default `/data/data`), preserving Desktop and Claude Code state across restarts. - Persistent sign-in through a bundled, auto-unlocked gnome-keyring. +- Configurable Claude Code permissions: strict prompts, automatic safe-action + approval, or explicit full bypass for trusted installations. - Optional runtime Claude Desktop updates from Anthropic's apt repository. - Optional extra apt and pip package installation (pip installs use `uv`). - Baked-in `git`, GitHub CLI (`gh`), `ripgrep`, `jq`, `shellcheck`, `yamllint`, @@ -70,7 +74,7 @@ Git synchronization hooks. A repository is indexed only when it is listed in Assistant. - Independent hourly savings reports for Headroom, RTK, and TokenSave. - `claude-tools-doctor.sh` diagnostics for binaries, routing, hooks, MCP - registrations, project indexes, proxy health, and gains. + registrations, project indexes, proxy health, permissions, and gains. - Low-power defaults for GPU mapping, Selkies frame rate, and volatile caches. ## Options @@ -84,6 +88,7 @@ Git synchronization hooks. A repository is indexed only when it is listed in | `DRINODE` | | Optional GPU device override for Selkies. | | `DNS_server` | `8.8.8.8` | DNS server used by the standard DNS module. | | `auto_update` | `true` | Upgrade `claude-desktop` from Anthropic's apt repository at startup. | +| `permission_mode` | `auto` | Claude Code permission policy: `strict`, `auto`, or `bypass`. | | `install_headroom` | `true` | Register Headroom MCP and run the supervised local proxy. | | `headroom_wrap_claude_code` | `true` | Route PATH-based Claude Code launches through the already-running Headroom proxy. | | `expose_headroom_dashboard` | `false` | Bind Headroom to all interfaces. Port `8787/tcp` must also be mapped manually. | @@ -104,6 +109,23 @@ Git synchronization hooks. A repository is indexed only when it is listed in | `data_location` | `/data/data` | Persistent home directory for Claude and tooling. | | `env_vars` | `[]` | Additional environment variables exported inside the container. | +### Permission modes + +```yaml +permission_mode: auto +``` + +- `strict` keeps Claude Code's normal interactive permission prompts. +- `auto` asks Claude Code's automatic permission classifier to approve safe + operations while retaining prompts for risky actions. This is the default. +- `bypass` disables Claude Code permission checks by using + `bypassPermissions` in the shared settings and + `--dangerously-skip-permissions` for wrapper-launched sessions. + +`bypass` gives Claude broad authority over all mounted writable data and every +command or credential available inside the add-on. Enable it only in a trusted +installation with trusted repositories and mounts. + ### TokenSave project example Only repositories listed here are indexed. Paths must be absolute, mounted in @@ -118,6 +140,8 @@ tokensave_project_paths: At startup, an uninitialized repository receives `tokensave init`; an existing index receives an incremental `tokensave sync`. Removing a path from the option stops automatic synchronization but does not delete its `.tokensave` database. +Configured repositories are added to Git's `safe.directory` list for the shared +runtime user before TokenSave performs repository discovery. ## Headroom behavior @@ -148,9 +172,9 @@ claude-tools-doctor.sh ``` The report checks the tool binaries, configuration switches, redacted MCP -registrations, Claude hooks, Headroom health, TokenSave indexes, routing, and -recorded savings. It never prints MCP environment values because the Home -Assistant MCP entry can contain a long-lived token. +registrations, Claude hooks, permission mode, Headroom health, TokenSave indexes, +routing, and recorded savings. It never prints MCP environment values because +the Home Assistant MCP entry can contain a long-lived token. The hourly report can also be invoked manually: @@ -186,7 +210,8 @@ Persistent state is stored in the configured `data_location` (default - Claude Desktop sign-in: `~/.config/Claude` (token encrypted via gnome-keyring; keyring DB in `~/.local/share/keyrings`) -- Claude Code settings, hooks, sessions, and plugins: `~/.claude` +- Claude Code settings, hooks, sessions, plugins, and permission mode: + `~/.claude` - Headroom, RTK, and TokenSave user state: their standard paths below the shared home - TokenSave repository indexes: `.tokensave/` inside each explicitly configured