🐝 Brummer
Your Terminal UI Development Buddy with intelligent monitoring
A TUI (Terminal User Interface) for managing npm/yarn/pnpm/bun scripts with integrated MCP server for external tool access. Brummer provides intelligent log management, real-time monitoring, and seamless integration with development tools.
📖 Documentation
📚 Full documentation available at: https://standardbeagle.github.io/brummer/
Quick links:
Features
- Multi-Package Manager Support: Automatically detects and uses npm, yarn, pnpm, or bun
- Monorepo Support: Full support for pnpm workspaces, npm workspaces, yarn workspaces, Lerna, Nx, and Rush
- Multi-Language Detection: Auto-detects commands for Node.js, Go, Rust, Java (Gradle/Maven), .NET, Python, Ruby, PHP, Flutter, and more
- Interactive TUI: Navigate through scripts, monitor processes, and view logs in real-time
- Smart Log Management:
- Automatic error detection and prioritization
- Log filtering and search capabilities
- Build event and test result detection
- MCP Server Integration: Allows external tools (VSCode, Claude Code, etc.) to:
- Access log output and errors
- Execute commands asynchronously
- Monitor process status
- Process Management: Start, stop, and monitor multiple processes simultaneously
- VS Code Tasks: Detects and runs VS Code tasks from .vscode/tasks.json
- Environment Variable Management (Planned):
- Unified .env file management with multi-format support
- TUI view for browsing and editing environment variables
- Automatic injection for scripts and AI agents
- Secret detection and masking for security
Installation
Quick Install (One-Liner)
🐧 Linux/macOS
curl -sSL https://raw.githubusercontent.com/standardbeagle/brummer/main/quick-install.sh | bash
Or with wget:
wget -qO- https://raw.githubusercontent.com/standardbeagle/brummer/main/quick-install.sh | bash
🪟 Windows (PowerShell)
irm https://raw.githubusercontent.com/standardbeagle/brummer/main/quick-install.ps1 | iex
Package Managers
📦 NPM/NPX
# Run directly with npx (no installation)
npx @standardbeagle/brum
# Install globally
npm install -g @standardbeagle/brum
# Or with yarn
yarn global add @standardbeagle/brum
# Or with pnpm
pnpm add -g @standardbeagle/brum
🐹 Go Install
go install github.com/standardbeagle/brummer/cmd/brum@latest
Install from Source
Build from source
# Clone the repository
git clone https://github.com/standardbeagle/brummer
cd brummer
# Using Make (recommended)
make install-user # Install for current user (~/.local/bin)
# OR
make install # Install system-wide (requires sudo)
# Using the interactive installer
./install.sh
# Manual build
go build -o brum ./cmd/brum
mv brum ~/.local/bin/ # Add to PATH
Usage
Basic Usage
In a directory with a package.json file:
brum
Options
brum [flags]
Flags:
-d, --dir string Working directory containing package.json (default ".")
-p, --port int MCP server port (default 7777)
--no-mcp Disable MCP server
--settings Show current configuration settings with sources
-h, --help help for brum
TUI Navigation
- Tab: Switch between views (Scripts, Processes, Logs, Errors, URLs, Settings)
- ↑/↓ or j/k: Navigate items
- Enter: Select/execute
- n: Open run command dialog (from Scripts tab)
- Esc or q: Go back
- /: Search logs
- p: Toggle high-priority logs
Process Management
- Navigate: Use ↑/↓ arrows to select a process (shows status with colored indicators)
- s: Stop selected process (only works on running processes 🟢)
- r: Restart selected process (stops then starts the same script)
- Ctrl+R: Restart all running processes
- Enter: View logs for selected process
Process Status Indicators:
- 🟢 Running - Process is active (can stop/restart)
- 🔴 Stopped - Process was manually stopped
- ❌ Failed - Process exited with error
- ✅ Success - Process completed successfully
- ⏸️ Pending - Process is starting up
Automatic Cleanup:
- All running processes are automatically stopped when Brummer exits
- Use Ctrl+C or 'q' to quit with graceful cleanup
- Process count shown in header: "Running Processes (2)"
Log Management
- c: Copy most recent error to clipboard
- f: View/manage filters
Other
- ?: Show help
- Ctrl+C: Quit
Configuration
Brummer supports hierarchical configuration through .brum.toml files. Configuration is loaded in the following order (later values override earlier ones):
~/.brum.toml(global user settings)- Project root and parent directories (walking up to root)
- Current working directory
.brum.toml
Viewing Current Configuration
# Show current settings with source files
brum --settings
# Create a configuration file from current settings
brum --settings > .brum.example.toml
Configuration Options
Create a .brum.toml file in your project or home directory:
# Package manager preference
preferred_package_manager = "pnpm" # npm, yarn, pnpm, bun
# MCP Server settings
mcp_port = 7777
no_mcp = false
# Proxy settings
proxy_port = 19888
proxy_mode = "reverse" # "reverse" or "full"
proxy_url = "http://localhost:3000" # Optional: auto-proxy this URL
standard_proxy = false
no_proxy = false
Settings Tab
The Settings tab provides:
- Package Manager Selection: Choose between npm, yarn, pnpm, or bun
- MCP Server Installation: One-click installation for development tools:
- Claude Desktop ✓
- Claude Code ✓
- Cursor ✓
- VSCode (with MCP extension) ✓
- Cline ✓
- Windsurf ✓
- Roo Code (experimental)
- Augment (experimental)
- Cody (experimental)
MCP Hub Mode 🆕
Brummer Hub Mode enables MCP clients to discover and control multiple brummer instances through a single connection:
Quick Setup
-
Configure your MCP client once:
{ "servers": { "brummer-hub": { "command": "brum", "args": ["--mcp"] } } } -
Run brummer in each project:
cd ~/projects/frontend && brum cd ~/projects/backend && brum -
Use hub tools in your MCP client:
instances/list- See all running instancesinstances/connect- Connect to a specific instance- All instance tools become available with prefixes
MCP Server Integration
The MCP server runs on port 7777 by default and implements the official MCP Streamable HTTP transport protocol:
Transport Protocol
Single Endpoint: http://localhost:7777/mcp
Connection Types:
- Standard JSON-RPC (POST with
Accept: application/json) - Server-Sent Events (GET with
Accept: text/event-stream) - SSE Response (POST with
Accept: text/event-stream)
Example Connection
// SSE streaming connection
const eventSource = new EventSource('http://localhost:7777/mcp');
eventSource.onmessage = (event) => {
const msg = JSON.parse(event.data);
console.log('Received:', msg);
};
// Send JSON-RPC requests
fetch('http://localhost:7777/mcp', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/list'
})
});
Available Tools
Script Management: scripts_list, scripts_run, scripts_stop, scripts_status
Log Management: logs_stream, logs_search
Browser Tools: browser_open, browser_screenshot, browser_navigate, repl_execute
Proxy Tools: proxy_requests
Telemetry: telemetry_sessions, telemetry_events
Examples
Run in a specific directory
brum -d ~/projects/my-app
Run with custom MCP port
brum -p 8888
Run without MCP server (TUI only)
brum --no-mcp
Run in headless mode (MCP server only)
brum --no-tui
Development
Project Structure
brummer/
├── cmd/brum/ # Main application entry point
├── internal/
│ ├── tui/ # Terminal UI components
│ ├── process/ # Process management
│ ├── mcp/ # MCP server implementation
│ ├── logs/ # Log storage and detection
│ └── parser/ # Package.json parsing
├── pkg/
│ ├── events/ # Event system
│ └── filters/ # Log filtering
└── go.mod
Building
go build -o brum ./cmd/brum
Testing
go test ./...
License
MIT