Configuration

Desktop App Settings

The desktop app stores configuration in %APPDATA%/BumbaClaude/config.json. You can edit this file directly or through the app's settings UI.

config.json structure

{
  "window": {
    "width": 1400,
    "height": 900,
    "x": 100,
    "y": 100
  },
  "tray": {
    "closeToTray": true,
    "minToTrayOnStart": false
  },
  "updates": {
    "autoCheck": true,
    "checkInterval": 3600000
  },
  "hotkey": {
    "globalShowHide": "CommandOrControl+Shift+B"
  },
  "notifications": {
    "taskComplete": true,
    "agentError": true,
    "waitingForInput": true,
    "governanceLimit": true
  },
  "database": {
    "path": "%APPDATA%/BumbaClaude/dashboard.db"
  }
}

Settings explained

window

• width, height -- Window size in pixels
• x, y -- Window position (auto-saved after moving/resizing)

tray

• closeToTray -- When true, clicking X minimizes to tray (doesn't quit). Default: true
• minToTrayOnStart -- When true, app starts minimized to tray. Default: false

updates

• autoCheck -- Check for updates on launch. Default: true
• checkInterval -- Check for updates every N milliseconds. Default: 3600000 (1 hour)

hotkey

• globalShowHide -- Global keyboard shortcut to show/hide the window. Default: CommandOrControl+Shift+B
• Other hotkey options (not yet supported): open-dev-tools, reload-window

notifications

• taskComplete -- Notify when an agent completes a task. Default: true
• agentError -- Notify when an agent encounters an error. Default: true
• waitingForInput -- Notify when an agent is waiting for human input. Default: true
• governanceLimit -- Notify when an agent hits a governance limit (max turns). Default: true

database

• path -- Full path to the SQLite database file. Don't change unless you know what you're doing.

Governance Rules

Governance rules are set per team at creation and apply to all agents in that team.

Rule types

can_create_files (boolean)

• Default: true
• When false, agents cannot create new files (they can edit existing ones)
• Useful for read-only exploration of a codebase

can_run_commands (boolean)

• Default: true
• When false, agents cannot execute shell commands
• Agents can still read files and invoke tools

can_push_git (boolean)

• Default: true
• When false, agents cannot commit or push to git
• Useful for non-destructive analysis tasks

max_turns (integer, 5-50)

• Default: 20
• After N agent responses, the agent must wait for human approval before continuing
• Prevents runaway agent loops
• Override per-agent by messaging the agent to continue

Environment Variables

Configuration via environment variables (used during development or when running from source):

# Database
DATABASE_PATH=./data/dashboard.db

# WebSocket
WS_PORT=3001

# Node environment
NODE_ENV=development  # or production

# Next.js
NEXTAUTH_SECRET=  # Optional, for future auth

# Claude Code
CLAUDE_HOME=/home/user/.claude  # Override default ~/.claude/

For the desktop app, set these in the .env.local file in the BumbaClaude install directory:

%APPDATA%/BumbaClaude/.env.local

Accessing Configuration from Code

From Next.js (backend)

// Get config value
import db from '@/lib/db';
const teams = db.query('SELECT * FROM teams').all();

// Environment variables
const dbPath = process.env.DATABASE_PATH || './data/dashboard.db';

From React (frontend)

Configuration is passed to the frontend via API routes. Don't hardcode config in components.

// Fetch from API
const response = await fetch('/api/config');
const config = await response.json();

From Electron main process

// Read config.json
import { app } from 'electron';
import path from 'path';
import fs from 'fs';

const configPath = path.join(app.getPath('userData'), 'config.json');
const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));

Permissions and File Access

BumbaClaude requires permission to:

1. Read/write to %APPDATA% -- Configuration and database storage
2. Read ~/.claude/ -- Team and task state
3. Execute tmux -- Spawn and manage agent sessions
4. Read/write working directories -- Only for Claude Code to use (BumbaClaude reads, doesn't write)

The app never:

• Writes to ~/.claude/ (read-only)
• Modifies Claude Code files
• Accesses files outside the specified working directory

Troubleshooting Configuration

Config file corrupted

• Delete %APPDATA%/BumbaClaude/config.json
• Restart the app to regenerate with defaults

Settings not saving

• Check if config.json is readable/writable: Right-click > Properties > Security
• Ensure the AppData folder has write permissions
• Run the app as Administrator to reset permissions

Global hotkey not working

• Hotkey may conflict with another app
• Try a different key combination (e.g., CommandOrControl+Shift+C)
• Edit config.json directly to change it

Tray icon not showing

• Reload the app (Ctrl+Shift+R)
• Check Windows Settings > System > Taskbar > Taskbar corner overflow
• The icon may be hidden; click the ^ to reveal it

Notifications not appearing

• Check Windows Settings > System > Notifications
• BumbaClaude should have "Show notifications" enabled
• Some versions of Windows filter notifications per app