Control which projects can use Bob Shell's full capabilities with trusted folder security.

Trusted folders give you control over which projects can be used with Bob Shell. You must approve a folder before Bob Shell loads any project-specific configurations, protecting you from potentially malicious code.

Note:

The trusted folders feature is disabled by default. To enable it, open the /settings menu and set Folder Trust to true. A restart is required for the change to take effect.

How trusted folders work

When you run Bob Shell from a folder for the first time, a trust dialog appears automatically, prompting you to make a choice:

Trust folder: Grant full trust to the current folder (for example, my-project)

Trust parent folder: Grant trust to the parent directory (for example, safe-projects), which automatically trusts all of its subdirectories. Use this option if you keep all your safe projects in one location

Don't trust: Mark the folder as untrusted. Bob Shell operates in a restricted safe mode

Your choice is saved in ~/.bob/trustedFolders.json, so you are only asked once per folder.

Trust levels

The ~/.bob/trustedFolders.json file stores one trust entry per folder. Each entry uses one of three trust levels:

Trust level	Effect
`TRUST_FOLDER`	Grants full trust to the exact folder path. Project settings, hooks, modes, skills, and MCP servers all load normally.
`TRUST_PARENT`	Grants full trust to the specified directory and all subdirectories beneath it. Use this level to cover a workspace root that contains multiple repos.
`DONT_TRUST`	Marks the folder as untrusted. Bob Shell runs in restricted safe mode and blocks all project-specific configurations. See Impact of untrusted folders.

Folders with no entry in ~/.bob/trustedFolders.json are called unresolved. How Bob Shell treats unresolved folders depends on whether the trusted folders feature is enabled. See Non-interactive sessions for details.

Impact of untrusted folders

When a folder is untrusted, Bob Shell runs in restricted safe mode. The following features are disabled or ignored:

Feature	Behaviour in safe mode
Project settings	`.bob/settings.json` is not loaded. Custom tools and potentially dangerous configurations are blocked.
Tool auto-approval	You are always prompted before any tool runs, even if auto-approval is enabled globally.
MCP servers	Bob Shell will not attempt to connect to any MCP servers.
Custom modes	Modes defined in the project folder are unavailable. Only built-in modes and your globally defined modes can be used.
Skills	Project-bundled skills are not loaded. Only globally available skills and built-in capabilities are active.
Subagents	Custom subagents from the project folder are unavailable. The agent cannot delegate work to project-provided helpers.
Project instructions	Guidance files such as `AGENTS.md` and custom project rules are not read. The agent operates without the project's custom instructions.

Granting trust to a folder unlocks the full functionality of Bob Shell for that workspace.

Managing trust settings

How trust is resolved: Bob Shell checks ~/.bob/trustedFolders.json for an existing decision for the current folder.
Change the current folder's trust: Run the /permissions slash command from within Bob Shell. The interactive dialog appears, allowing you to change the trust level for the current folder.
View all trust rules: Inspect ~/.bob/trustedFolders.json in your home directory for a complete list of all your trusted and untrusted folder rules.

Non-interactive sessions

Unlike interactive mode, non-interactive sessions (bob run) never display the trust dialog. Bob Shell operates silently based on pre-existing trust decisions.

Default behavior when the feature is disabled

When the trusted folders feature is disabled (the default), Bob Shell treats every folder as trusted. Project settings, hooks, modes, skills, and MCP servers load for every folder without restriction, regardless of whether an entry exists in ~/.bob/trustedFolders.json.

Behavior when the feature is enabled

When the trusted folders feature is enabled, Bob Shell evaluates the trust level of the working folder before loading any project-specific content:

Unresolved folder (no entry in ~/.bob/trustedFolders.json): The folder is treated as trusted. Project settings and hooks load normally.

TRUST_FOLDER or TRUST_PARENT entry: The folder is trusted. Full functionality is available.

DONT_TRUST entry: Bob Shell throws an error and does not run:

<folder> is not a trusted folder. Pass --trust to run in this folder,
or run Bob Shell interactively and choose a trust level.

Warning:

Enabling the trusted folders feature alone does not block hook execution for folders with no trust decision. An unresolved folder — for example, a repository cloned for the first time in a CI/CD pipeline — is treated as trusted. Only an explicit DONT_TRUST entry prevents hooks and project settings from loading.

Hook execution in headless mode

Global hooks defined in ~/.bob/settings/settings.json execute for every folder that is not explicitly marked DONT_TRUST, including unresolved folders. Workspace hooks defined in .bob/settings.json inside the project are also subject to folder trust: they load only when the folder is trusted or unresolved, and are silently skipped when the folder is DONT_TRUST.

To understand which hooks are configured and what they do before running bob run against an unfamiliar repository, see Lifecycle hooks.

Flag behaviour by mode

The --trust and --auto-approve flags behave differently depending on how Bob Shell is launched. Select your mode to see the relevant behaviour:

--trust: The folder is persisted as trusted. Bob Shell writes a trusted entry for the current directory to ~/.bob/trustedFolders.json and skips the first-access trust dialog. This is equivalent to opening the folder and manually selecting "Trust folder."
--auto-approve: Auto-approval is silently suppressed in an untrusted folder. You are still prompted before every tool runs.

--trust: The folder is treated as trusted for that run only. The trust decision is not persisted and nothing is written to the trust store.

Hardening automation pipelines

If you run bob run in a CI/CD pipeline against repositories you do not control — for example, third-party or open-source repos cloned as part of a build — take the following steps to prevent untrusted hook code from executing.

Before you begin: Enable the trusted folders feature by setting security.folderTrust.enabled to true in ~/.bob/settings/settings.json. A restart is required for the change to take effect.

Decide which directories you control and add a TRUST_PARENT entry to ~/.bob/trustedFolders.json for each one. This covers all repositories beneath a known workspace root and leaves everything outside that tree as unresolved.

{
  "/home/runner/work/my-org": "TRUST_PARENT"
}

For any repository that you clone from an external or untrusted source, add a DONT_TRUST entry before running bob run:

{
  "/home/runner/work/my-org": "TRUST_PARENT",
  "/home/runner/work/third-party-repo": "DONT_TRUST"
}

Review the global hooks configured in ~/.bob/settings/settings.json. Global hooks execute for every trusted or unresolved folder, including all repos covered by a TRUST_PARENT entry. Remove or scope any hooks that must not run against untrusted code.

Before running bob run against any cloned repository, review .bob/settings.json inside that repository for workspace hooks, just as you would review a Makefile or CI configuration file. Workspace hooks load in any trusted or unresolved folder.

After completing these steps, Bob Shell blocks project settings and hooks for any folder with a DONT_TRUST entry, while still allowing bob run to operate normally in your controlled workspace.

Best practices

Trust only folders containing code you have reviewed or created yourself

Use TRUST_PARENT for directories that contain multiple safe projects to avoid managing individual folder entries

Regularly review ~/.bob/trustedFolders.json to audit which folders are trusted

When working with unfamiliar code, add a DONT_TRUST entry for the cloned directory before running bob run

Review global hooks in ~/.bob/settings/settings.json periodically — they execute in every trusted and unresolved folder

Trusted folders

On this page