Development - twamp22/BumbaClaude GitHub Wiki

Development

Getting Started

Clone the repository and set up your development environment.

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

Prerequisites

  • Node.js v24.0.0 or later
  • pnpm v9.0.0 or later
  • Git
  • tmux (for testing agent spawning)
  • Claude Code CLI installed and in PATH

Verify setup

node --version        # Should be v24.0.0+
pnpm --version        # Should be v9.0.0+
tmux -V               # Should show tmux version
claude --version      # Should show Claude Code version

Development Commands

Browser-only development

pnpm dev

Starts the Next.js dev server at http://localhost:3000. No Electron needed. Hot reload enabled.

Desktop app development

pnpm electron:dev

Runs the Next.js dev server with hot reload + Electron in development mode. Loads the browser into a native window with dev tools enabled.

Building for production

pnpm build

Builds the Next.js app. No Electron involved. Run this before pnpm electron:build.

Building the Electron installer

pnpm electron:build
  1. Builds Next.js with pnpm build
  2. Compiles Electron TypeScript files
  3. Packages with electron-builder
  4. Creates BumbaClaude Setup 0.1.0.exe and portable .zip

Output goes to the dist/ folder.

Linting and type checking

pnpm lint

Runs ESLint to check for code style issues.

pnpm build

Also type-checks the entire codebase via TypeScript.

Code Conventions

All contributions must follow these conventions (enforced via linting):

TypeScript

  • Strict mode enabled (tsconfig.json)
  • No any types (use unknown if needed, then narrow)
  • No unused variables
  • Descriptive variable names (no single letters except loop counters i, j)

React Components

  • Server components by default (/src/app/ pages)
  • Client components only when interactivity requires it ('use client' at top)
  • Use hooks for state management (useEffect, useState, etc.)
  • Component names in PascalCase (TeamCard.tsx, not teamCard.tsx)

API Routes

  • All backend operations go in /src/app/api/
  • Use HTTP methods correctly (GET for reads, POST for creation, PATCH for updates, DELETE for removal)
  • Return JSON with consistent error structure: { error: "message", code: "ERROR_CODE" }
  • Always set appropriate HTTP status codes (200, 201, 400, 404, 500, etc.)

Database

  • All database queries go through /src/lib/db.ts
  • Use parameterized queries to prevent SQL injection: db.query("SELECT * FROM teams WHERE id = ?", [id])
  • No ORM. Raw SQL only.
  • Transactions for multi-step operations: db.transaction(() => { ... })

tmux Operations

  • All tmux commands go through /src/lib/tmux.ts
  • Never shell out to tmux directly from component code
  • Wrap in try/catch with meaningful error messages

File System Access

  • All filesystem watching goes through /src/lib/watcher.ts
  • Never write to ~/.claude/ (read-only access)
  • Use absolute paths, not relative paths

Error Handling

  • Always catch errors: try { ... } catch (error) { console.error(...) }
  • Never swallow errors silently
  • Log server-side errors to console: console.error("Failed to spawn agent", error)
  • Return meaningful error messages to the frontend
  • No stack traces in user-facing error messages

UI Text

  • No em dashes (--) in any user-facing text. Use hyphens (-) or write it out.
  • Clear, concise language
  • Avoid jargon where possible
  • Capitalize properly (Title Case for headings, sentence case for body text)

Project Architecture

See Architecture for a detailed overview.

Key principle: The Wrapper Boundary

BumbaClaude NEVER modifies Claude Code internals.

All interaction happens through:

  1. tmux commands -- Spawn and control agent sessions
  2. Filesystem reads -- Read state from ~/.claude/
  3. Agent SDK (v0.2+) -- Programmatic control via official API

This boundary is non-negotiable. If a feature requires modifying Claude Code:

  1. Propose the feature upstream to Anthropic
  2. Wait for them to implement it in Claude Code
  3. Then integrate it into BumbaClaude

File structure

/src/app/              -- Next.js pages and API routes
/src/components/       -- React components organized by feature
/src/lib/              -- Core library (db, tmux, watcher, websocket, types)
/src/hooks/            -- Custom React hooks
/db/                   -- SQLite schema and migrations
/electron/             -- Electron main process code
/data/                 -- SQLite database (gitignored)

Contributing Workflow

  1. Fork the repo on GitHub

  2. Create a feature branch

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix-name

  3. Make your changes

    • Follow code conventions above
    • Keep commits focused (one feature per commit)
    • Write clear commit messages

  4. Test your changes

    pnpm lint           # Check linting
pnpm build          # Type-check and build
pnpm electron:dev   # Test in Electron

  5. Push to your fork

    git push origin feature/your-feature-name

  6. Open a pull request against the main repo's main branch

    • Link any related issues
    • Describe what your PR does
    • Mention if there are breaking changes

Testing

Manual testing

Since BumbaClaude controls tmux sessions, automated testing is limited. Most testing is manual:

  1. Team creation -- Create a team with different agent configurations
  2. Agent spawning -- Verify agents spawn and connect correctly
  3. Task management -- Create, assign, and complete tasks
  4. Audit log -- Check events are recorded with correct timestamps
  5. Governance -- Test that rules are enforced

Verifying tmux availability

Before running any tests:

tmux -V                                        # Verify tmux installed
tmux new-session -d -s test-session            # Create a test session
tmux kill-session -t test-session              # Kill the test session

If these commands fail, you're missing tmux. Install it via WSL2, MSYS2, or your preferred package manager.

Building the Installer

The Electron installer is built using electron-builder with NSIS (Windows installer format).

pnpm electron:build

This:

  1. Builds Next.js with pnpm build
  2. Compiles Electron TypeScript
  3. Creates:
    • dist/BumbaClaude Setup 0.1.0.exe -- Windows installer
    • dist/BumbaClaude-0.1.0-win.zip -- Portable zip

The installer uses NSIS to:

  • Install to Program Files
  • Create Start Menu shortcuts
  • Add an uninstaller
  • Support optional auto-start on Windows startup

Versioning Policy

BumbaClaude uses semantic versioning: MAJOR.MINOR.PATCH

  • v0.x.x -- Pre-1.0 development phase (breaking changes OK)
  • v1.0.0 -- Stable API and feature set
  • v1.1.0 -- New features, backward compatible
  • v1.1.1 -- Bug fixes only

Bump version in:

  1. package.json (version field)
  2. Create a git tag: git tag v0.1.0
  3. Push the tag: git push origin v0.1.0
  4. Create a GitHub Release from the tag

Debugging

Enable verbose logging

# Set Node.js debug env var
NODE_DEBUG=http,sqlite DEBUG=bumbaClaude:* pnpm dev

Inspect database

# Query the database directly
sqlite3 ./data/dashboard.db
sqlite> SELECT * FROM teams;
sqlite> .quit

View Electron dev tools

In pnpm electron:dev, press Ctrl+Shift+I to open dev tools (browser DevTools).

For the main process, use VS Code's remote debugging or inspect via DevTools.

Monitor file watcher

Add logging to /src/lib/watcher.ts:

watcher.on('change', (path) => {
  console.error('[watcher] File changed:', path);
  // ... rest of handler
});

Common Issues During Development

"Port 3000 already in use"

# Find and kill the process
netstat -ano | findstr :3000
taskkill /PID {PID} /F

# Or let Node pick a random port
PORT=3001 pnpm dev

"Database is locked"

  • Another instance of the app is using it
  • Quit all instances of BumbaClaude
  • Delete ./data/dashboard.db to reset
  • Restart the dev server

"tmux: command not found"

  • tmux is not installed or not in PATH
  • On Windows, install via WSL2 or MSYS2
  • On WSL2: apt install tmux
  • Add tmux to your PATH if installed elsewhere

"Electron won't start"

  • Check Node version: node --version (should be v24+)
  • Try pnpm electron:dev instead of running the packaged app
  • Check AppData folder has write permissions
  • Kill any running Electron processes: taskkill /IM BumbaClaude.exe /F

Deployment

Release checklist

Before creating a release:

  1. All tests pass: pnpm build
  2. Linting passes: pnpm lint
  3. Version bumped in package.json
  4. Changelog updated in /docs/changelog/
  5. PR merged to main
  6. Tag created: git tag v0.1.0

Then:

git push origin main
git push origin v0.1.0

pnpm electron:build

Upload the .exe and .zip files to GitHub Releases.

Auto-update flow

Once uploaded to GitHub Releases, users with auto-update enabled will:

  1. Get notified of the new version
  2. See an "Install update" button in the app
  3. Click to download and install
  4. App restarts with the new version