Installation - twamp22/BumbaClaude GitHub Wiki

Installation

System Requirements

Requirement Minimum Why
OS Windows 10 Pro or later Electron support, tmux on WSL2
Node.js v24.0.0 or later Runtime for Next.js and Electron
Claude Code CLI Latest version Required for agent spawning
tmux Available Session management for agents

For WSL2 users: Install tmux in your WSL2 distribution (apt install tmux on Ubuntu) and configure Claude Code to run in WSL2.

Desktop App Download

Download the latest release from GitHub:

  • BumbaClaude Setup 0.1.0.exe -- Windows installer (recommended)

    • Installs to Program Files
    • Creates Start Menu shortcuts
    • Supports auto-update

  • BumbaClaude-0.1.0-win.zip -- Portable version

    • Extract and run BumbaClaude.exe directly
    • No install needed, works from any folder

Both require Node.js 24+ and Claude Code already installed.

Windows SmartScreen: On the first run, Windows may silently block the installer because it is unsigned. If nothing happens when you double-click the .exe, right-click it and select "Run as administrator", or try running it a second time. Windows caches the security scan after the first attempt.

Setup

Installed version

  1. Run the installer (.exe)
  2. Accept the license agreement
  3. Choose installation folder (default: Program Files)
  4. Check "Create Start Menu shortcuts" (recommended)
  5. Check "Launch on Windows startup" (optional)
  6. Click Install

Portable version

  1. Download BumbaClaude-0.1.0-win.zip
  2. Extract to any folder
  3. Run BumbaClaude.exe

The app creates a settings folder in %APPDATA%/BumbaClaude/ for configuration and database files.

From-Source Setup

Clone the repository and set up the development environment:

git clone https://github.com/twamp22/BumbaClaude.git
cd BumbaClaude
pnpm install

Running the desktop app

pnpm electron:dev

Starts the Next.js dev server (port 3000) with hot reload and Electron in development mode.

Running in browser only

pnpm dev

Opens the dashboard at http://localhost:3000 (no Electron needed).

Building the installer

pnpm electron:build

Creates a Windows installer and portable zip in the dist/ folder.

Verifying Your Setup

Before launching BumbaClaude:

  1. Verify tmux is installed: tmux -V
  2. Verify Claude Code CLI: claude --version
  3. Create a test tmux session: tmux new-session -d -s test
  4. Kill the test session: tmux kill-session -t test

If all commands succeed, you're ready to launch BumbaClaude.

First Run

On first launch:

  1. The app creates a SQLite database at %APPDATA%/BumbaClaude/dashboard.db
  2. The main dashboard loads at http://localhost:3000 (for dev builds)
  3. The tray icon appears (right-click for options)
  4. You can create your first agent team

Troubleshooting

"Claude Code CLI not found"

  • Verify the claude command is in your PATH: where claude
  • Reinstall Claude Code if needed

"tmux not found"

  • On Windows: Install tmux via WSL2 or MSYS2
  • On WSL2: apt install tmux in your distribution
  • Add tmux to PATH if installed outside standard locations

"Cannot connect to localhost:3000"

  • Check if port 3000 is in use: netstat -ano | findstr :3000
  • Kill the process if needed: taskkill /PID {PID} /F
  • Restart the app

Database lock errors

  • Quit the app completely
  • Delete %APPDATA%/BumbaClaude/dashboard.db (this resets all data)
  • Restart the app

Electron won't start

  • Try running pnpm electron:dev instead of the packaged app
  • Check Node.js version: node --version (should be v24+)
  • Check for permission issues in AppData folder