Configuring
You can configure Bob Shell to match your workflow preferences.
Settings file locations
Bob Shell stores settings in two locations:
| Scope | File |
|---|---|
| User (all workspaces) | ~/.bob/settings/settings.json |
| Project (current workspace) | <workspace>/.bob/ |
CLI flags always override file values for the current session. You can also change settings interactively with the /settings slash command inside bob chat.
Settings schema
{
"session": {
"maxTurns": 50,
"defaultMode": "agent",
"mcp": true,
"subagents": true
},
"logging": {
"logLevel": "warn"
},
"tasks": {
"retentionDays": 30
},
"telemetry": {
"enabled": true
}
}| Setting | Type | Default | Description |
|---|---|---|---|
session.maxTurns | number | 50 | Maximum agentic turns per session (0 = unlimited) |
session.defaultMode | string | "agent" | Default mode when starting a session |
session.mcp | boolean | true | Enable Model Context Protocol (MCP) servers by default |
session.subagents | boolean | true | Enable subagent spawning by default |
logging.logLevel | string | "warn" | Log verbosity (error, warn, info, debug, trace) |
tasks.retentionDays | number | 30 | Number of days to retain task history. Set to 0 to disable automatic cleanup and keep all task history. |
telemetry.enabled | boolean | true | Whether usage telemetry is sent. Disabling prevents usage data from being collected. |
telemetry.excludePayload | boolean | — | IBM users: exclude conversation payload from telemetry. Only enable for approved sensitive projects. |
Only set tasks.retentionDays to 0 in Bob Shell 2.0.1 or later. Setting this value to 0 in earlier versions can delete unpinned tasks and their history.
Authentication tokens (OAuth) are stored separately in ~/.bob/settings/auth-secrets.json.
Log files
Logs are written to ~/.bob/logs/shell/ using rotating files (bob-<timestamp>.log). Up to 10 log files are retained; older files are pruned automatically. The maximum log file size is 5 MB before rotation.
Use --log-level debug (or BOB_LOG_LEVEL=debug) to capture verbose output:
BOB_LOG_LEVEL=debug bob chat
bob run --log-level debug "Explain @app.js"You can also open the latest log file directly from within a session using the /logs slash command.
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.mdin project root and parent directories - Local context:
AGENTS.mdin 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 `!==`)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, set telemetry.enabled to false in your settings file:
{
"telemetry": {
"enabled": false
}
}