Getting started

You can configure Bob Shell using:

Project-specific settings: Create .bob/settings.json in your project directory
User-wide settings: Edit ~/.bob/settings.json in your home directory
Command-line arguments: Run --sandbox when starting Bob Shell

# Example: Start Bob Shell with sandbox mode enabled
bob --sandbox

Configuration system

How configuration works

Bob Shell uses a layered configuration system where settings from different sources are combined according to a specific precedence order:

Priority	Source	Location	Scope
1 (Highest)	Command-line arguments	`bob --option value`	Current session
2	Environment variables	Shell or `.env` files	System/session
3	System settings file	`/etc/bobshell/settings.json`	All users, all projects
4	Project settings file	`.bob/settings.json`	Current project
5	User settings file	`~/.bob/settings.json`	Current user, all projects
6	System defaults file	`/etc/bobshell/system-defaults.json`	All users, all projects
7 (Lowest)	Hardcoded defaults	Built into Bob Shell	Always applied

When the same setting is defined in multiple places, the higher-priority source takes precedence.

Settings file locations

Bob Shell looks for settings files in these locations:

Project settings: .bob/settings.json in your project directory
User settings: ~/.bob/settings.json in your home directory
System settings:

/etc/bobshell/settings.json

C:\ProgramData\bobshell\settings.json

/Library/Application Support/Bob Shell/settings.json

System defaults:

/etc/bobshell/system-defaults.json

C:\ProgramData\bobshell\system-defaults.json

/Library/Application\ Support/Bob\ Shell/system-defaults.json

Core settings categories

Bob Shell settings are organized into categories. Each category contains related settings that control specific aspects of Bob Shell's behavior.

General settings

Control basic Bob Shell behavior and preferences.

{
  "general": {
    "preferredEditor": "code",
    "vimMode": false,
    "disableAutoUpdate": false,
    "disableUpdateNag": false,
    "checkpointing": {
      "enabled": true
    }
  }
}

Setting	Type	Default	Description
`preferredEditor`	string	`undefined`	Editor to use when opening files
`vimMode`	boolean	`false`	Enable Vim keybindings
`disableAutoUpdate`	boolean	`false`	Prevent automatic updates
`disableUpdateNag`	boolean	`false`	Hide update notifications
`checkpointing.enabled`	boolean	`false`	Enable session checkpointing

UI settings

Customize Bob Shell's appearance and interface elements.

{
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": false,
    "showLineNumbers": true
  }
}

Setting	Type	Default	Description
`theme`	string	`undefined`	UI color theme
`customThemes`	object	`{}`	Custom theme definitions
`hideWindowTitle`	boolean	`false`	Hide window title bar
`hideTips`	boolean	`false`	Hide helpful tips
`hideBanner`	boolean	`false`	Hide application banner
`hideFooter`	boolean	`false`	Hide footer
`showMemoryUsage`	boolean	`false`	Show memory usage stats
`showLineNumbers`	boolean	`false`	Show line numbers in chat
`showCitations`	boolean	`false`	Show citations for generated text
`accessibility.disableLoadingPhrases`	boolean	`false`	Disable loading phrases

Context settings

Control how Bob Shell manages project context and memory.

{
  "context": {
    "fileName": ["CONTEXT.md", "AGENTS.md"],
    "discoveryMaxDirs": 200,
    "includeDirectories": ["../shared-lib", "~/reference-code"],
    "fileFiltering": {
      "respectGitIgnore": true,
      "respectBobIgnore": true
    }
  }
}

Setting	Type	Default	Description
`fileName`	string/array	`undefined`	Context file name(s)
`importFormat`	string	`undefined`	Memory import format
`discoveryMaxDirs`	number	`200`	Max directories to search
`includeDirectories`	array	`[]`	Additional directories to include
`loadFromIncludeDirectories`	boolean	`false`	Load context from included dirs
`fileFiltering.respectGitIgnore`	boolean	`true`	Honor .gitignore files
`fileFiltering.respectBobIgnore`	boolean	`true`	Honor .bobignore files
`fileFiltering.enableRecursiveFileSearch`	boolean	`true`	Enable recursive file search

Tools settings

Configure how Bob Shell uses and manages tools.

{
  "tools": {
    "sandbox": "docker",
    "allowed": ["run_shell_command(git)", "run_shell_command(npm test)"],
    "exclude": ["write_file"]
  }
}

Setting	Type	Default	Description
`sandbox`	boolean/string	`undefined`	Sandbox running environment
`usePty`	boolean	`false`	Use node-pty for shell commands
`core`	array	`undefined`	Restrict built-in tools (allowlist)
`exclude`	array	`undefined`	Tools to exclude from discovery
`allowed`	array	`undefined`	Tools that bypass confirmation
`discoveryCommand`	string	`undefined`	Command for tool discovery
`callCommand`	string	`undefined`	Command for calling tools

MCP settings

Configure Model Context Protocol server connections.

{
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "remoteServer": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token123"
      }
    }
  }
}

Setting	Type	Default	Description
`mcp.serverCommand`	string	`undefined`	Command to start MCP server
`mcp.allowed`	array	`undefined`	Allowlist of MCP servers
`mcp.excluded`	array	`undefined`	Denylist of MCP servers
`mcpServers.<SERVER_NAME>`	object	-	Server-specific configuration

For each MCP server, you can configure:

command: Command to run (for local servers)
args: Command-line arguments
env: Environment variables
cwd: Working directory
url: Server-Sent Events (SSE) endpoint URL (for remote servers)
httpUrl: HTTP endpoint URL (for remote servers)
headers: HTTP headers for requests
timeout: Request timeout in milliseconds
trust: Trust server and bypass confirmations
includeTools: Tool names to include
excludeTools: Tool names to exclude

Command-line arguments

Pass these arguments when starting Bob Shell to override settings for that session:

# Start Bob Shell with specific settings
bob --sandbox --approval-mode auto_edit

Argument	Description	Example
`--prompt`, `-p`	Non-interactive prompt	`bob -p "Explain this code"`
`--prompt-interactive`, `-i`	Interactive initial prompt	`bob -i "Help me debug"`
`--sandbox`, `-s`	Enable sandbox mode	`bob -s`
`--debug`, `-d`	Enable debug mode	`bob -d`
`--yolo`	Auto-approve all tool calls	`bob --yolo`
`--approval-mode`	Set tool approval mode	`bob --approval-mode=auto_edit`
`--allowed-tools`	Tools to auto-approve	`bob --allowed-tools="git status"`
`--include-directories`	Add directories to workspace	`bob --include-directories=../lib`
`--chat-mode`	Choose the mode for interaction	`bob --chat-mode`
`--hide-intermediary-output`	Output only the final task completion output	`bob --hide-intermediary-output`
`--show-license`	Show full path to license files for review	`bob --show-license`
`--accept-license`	Accept the IBM license agreement and continue	`bob --accept-license`
`--instance-id`	Instance ID to use for this Bob Shell session	`bob --instance-id=my-instance`
`--team-id`	Team ID to use for this Bob Shell session	`bob --team-id=my-team`

Context files

Context files (like AGENTS.md) provide instructions to the AI model. These files are loaded hierarchically:

Global context: ~/.bob/AGENTS.md (applies to all projects)
Project context: AGENTS.md in project root and parent directories
Local context: AGENTS.md in subdirectories (for component-specific instructions)

Example context file

# Project: My TypeScript Library

## General instructions

- Follow existing coding style
- Add JSDoc comments to all functions
- Prefer functional programming patterns
- Target TypeScript 5.0 and Node.js 20+

## Coding style

- Use 2 spaces for indentation
- Interface names should be prefixed with `I`
- Private class members should be prefixed with `_`
- Use strict equality (`===` and `!==`)

Managing context

Use /memory refresh to reload all context files
Use /memory show to view the current context

Sandboxing

Sandboxing provides security when running potentially unsafe operations:

# Enable sandboxing for a session
bob --sandbox

You can create custom sandbox environments:

Create .bob/sandbox.Dockerfile in your project
Base it on the bobshell-sandbox image
Add your custom dependencies

FROM bobshell-sandbox

# Add custom dependencies
RUN apt-get update && apt-get install -y python3-dev

Build and use your custom sandbox:

BUILD_SANDBOX=1 bob -s

Note:

The create-pr command is not compatible with Sandbox sessions.

Usage statistics

Bob Shell collects anonymous usage statistics to improve the product. This includes:

Tool usage patterns (names, success/failure, duration)
API request metrics (model, duration, success)
Session configuration information

No personal information, prompt content, or file content is collected.

To opt out, add this to your settings:

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

Configuring