@nomad-e/bluma-cli

v0.7.0

Published

16 hours ago

BluMa independent agent for automation and advanced software engineering.

0High
0Medium
0Low

alexfonseca05

BluMa CLI — AI-Powered Agent for Advanced Software Engineering

BluMa Background

BluMa is an independent AI agent CLI for automation and advanced software engineering. It combines powerful tool orchestration, multi-agent coordination, and intelligent context management to help you build software faster and with higher quality.

Latest Version: v0.6.4 (2026-05-10) — Circular dependency resolution, enhanced native tool metadata, improved multi-agent coordination, and professional release engineering.

🚀 Quick Start

# Install globally
npm install -g @nomad-e/bluma-cli

# Run BluMa (new session)
bluma

# Resume a previous session
bluma resume {session_id}

# Or run from source
npm install
npm run build
npm start

✨ Key Features

🤖 Native Tools (45+ tools)

Comprehensive toolset organized by category with risk levels and auto-approve policies.
Tools are now modularly structured in src/app/agent/tools/ with separate UI components:

Filesystem (10 tools):

ls_tool, read_file_lines, count_file_lines, find_by_name, grep_search
view_file_outline, edit_tool, file_write, notebook_edit, lsp_query

Execution (6 tools):

shell_command, command_status, send_command_input, kill_command
repl (interactive code execution for Python/Node/Bash)
task_output (real-time output following)

Communication (7 tools):

message, ask_user_question, brief, send_message
list_mailbox_messages, poll_mailbox, signal_mailbox

Planning (11 tools):

todo, task_boundary, task_create, task_update, task_stop
task_list, task_get, enter_plan_mode, exit_plan_mode
cron_create, cron_list, cron_delete

Knowledge (10 tools):

search_web, web_fetch, load_skill, coding_memory
ctx_inspect, dream, context_collapse, snip
list_mcp_resources, read_mcp_resource

Agent Coordination (4 tools):

spawn_agent, wait_agent, list_agents, kill_agent

FactorAI Sandbox (5 tools):

factorai.sh.create_next_app, factorai.sh.deploy_app
factorai.sh.get_app_status, factorai.sh.apply_app_changes
factorai.sh.redeploy_app

🧠 Multi-Agent Orchestration

Coordinator Mode: Product Owner + Engineering Manager hybrid that delegates to specialist workers
Parallel Execution: Launch multiple workers concurrently for research, implementation, and verification
Mailbox IPC: Bidirectional file-based communication between coordinator and workers
- list_mailbox_messages: Read progress updates, permission requests, and results
- poll_mailbox: Poll for new messages from workers
- signal_mailbox: Send ack/nack/progress/heartbeat signals
- File-based storage: ~/.bluma/mailboxes/{session_id}.in/out/sig (JSONL format)
Worker Types: Researchers, implementers, verifiers with specialized roles
Session Registry: Track and manage agent sessions with lifecycle events
Task Boundary Tracking: Use task_boundary to track orchestration phases (PLANNING, EXECUTION, VERIFICATION)

📝 Slash Commands (80+ commands)

Quick access to common operations across 5 categories:

Session Commands (25+):

/clear - Clear current session
/sessions - List all sessions
/attach - Attach to existing session
/follow - Follow session output
/bridge - Bridge multiple sessions
/status - Show session status
/logs - View session logs
/resume - Resume previous session
/kill - Terminate session
/compact - Compress context
/export - Export session
/summarize - Summarize conversation
/history - Command history
/share - Share session
/copy - Copy output to clipboard
/commit - Create git commit
/pr - Create pull request
/release - Professional release engineering
/snip - Extract conversation snippets
/collapse - Collapse context
/brief - Generate brief
/undo - Undo last action
/redo - Redo undone action
/thread - Thread management (list/new/resume/fork/rename/archive/delete)

Inspect Commands (30+):

/plugins - List plugins
/plugin - Plugin details
/diagnostics - Run diagnostics
/permissions - Show permissions
/features - List features
/hooks - Hook registry
/model - Model info
/effort - Effort estimation
/style - Code style
/sandbox - Sandbox status
/worktree - Worktree info
/statusline - Status line config
/skills - List skills
/tools - List tools
/mcp - MCP resources
/debug-workers - Worker debug
/cost - Cost tracking
/memory - Memory usage
/stats - Session stats
/theme - Theme config
/keybindings - Key bindings
/vim - Vim mode
/ctx - Context inspector
/dream - Dream engine status
/diff - Show recent changes
/editor - Open in editor
/config - Runtime config
/file - File operations
/search - Search codebase
/context - Context management
/token - Token usage
/settings - Runtime settings
/alias - Manage aliases
/macro - Execute macros
/thread stats - Thread statistics

Agent Commands (15+):

/agent - Agent info
/agents - List agents
/img / /image - Image handling
/init - Initialize project
/review - Code review
/explain - Explain code
/fix - Fix errors
/debug - Debug issues
/bug - Report bug
/test - Run tests
/optimize - Optimize code
/refactor - Refactor code
/document - Generate docs
/chat - Chat mode
/code - Code mode
/terminal - Terminal placeholder
/template - Create from template

Input Methods:

Ctrl+V / Cmd+V - Paste image/text/file
Ctrl+Shift+I - Same as Ctrl+V

🎯 Intelligent Context Management

Auto Memory: Persistent coding notes across sessions (coding_memory)
Context Collapse: Advanced history compaction with multiple strategies (aggressive, moderate, minimal, target token budget)
Snip Tool: Extract and remove old conversation snippets (extract/remove/auto modes)
Dream Engine: Background memory consolidation — deduplicates, merges, prunes, and enriches coding memory entries
Token Tracking: Real-time token usage monitoring with ctx_inspect
Thread Management: Full thread lifecycle with create, resume, fork, rename, archive, delete operations

🛠️ Plan Mode

Structured problem-solving workflow with 3 phases:

PLANNING: Research and design
EXECUTION: Implementation
VERIFICATION: Testing and validation

🔧 Skills System (6 skills)

Extendable expertise modules with progressive disclosure — load only when needed:

Available Skills:

git-commit: Conventional commits automation with BluMa watermark
git-pr: Pull request creation and management (descriptions, reviewers, draft mode)
git-release: Full release engineering (version bumps, changelog, tags, npm publish, GitHub releases)
pdf: PDF generation and manipulation (reports, merge, forms, OCR)
xlsx: Spreadsheet processing (create, edit, formulas, charting, cleaning)
skill-creator: Create custom skills

How Skills Work:

Discovery: Skills loaded from dist/config/skills/, {cwd}/.bluma/skills/, ~/.bluma/skills/
Progressive Disclosure:
- Level 1: One-line description (always visible)
- Level 2: Full instructions (loaded on activation)
- Level 3: References and scripts (loaded on demand)
Triggering: Agent auto-detects when to load skills based on task context
Priority: Native > Project > Global (native skills cannot be overridden)

Create Custom Skills: See docs/SKILLS.md for complete guide on authoring skills.

🎨 Modern UI

Built with Ink (React for CLI)
Shimmer effects for working states (WorkingShimmerText, Spinner with ShimmerChar/FlashingChar)
Streamlined transcript with syntax highlighting (HighlightedCode, MarkdownRenderer)
Bottom dock for status and controls (BlumaBottomDock, StatusBar)
Worker overlay for multi-agent visualization (WorkerOverlay, WorkerStatusList)
Real-time streaming (StreamingMarkdown, StreamingText, TypewriterText)
Animated indicators (Spinner, ProgressBar)
Theme system with configurable themes (blumaTerminal theme)

🔒 Sandbox Security

Permission modes: Local (auto-approve) vs Sandbox (confirmation required)
Policy enforcement: rm -rf protection, sudo blocking, dangerous command detection
Tool risk levels: safe, write, execute, network — with per-mode auto-approve settings
FactorAI integration: Optional sandbox backend for isolated execution with workspace manifest persistence

📦 Performance

TypeScript: Full type safety with strict mode
ES Modules: Modern module system with bundler resolution
React 19: Latest React with concurrent features
Optimized rendering: Memoized message blocks, offscreen freeze, expandable previews
Parallel tests: Up to 8 workers for faster test execution
Native modules: Rust-based clipboard and layout engine for critical paths

🔌 Hooks & Plugins

Extensible architecture with hook registry and plugin system:

Hook Registry: Execute custom scripts on events (pre-commit, post-build, etc.)
Plugin System: Extend BluMa with custom plugins
Event-driven: Hooks triggered by tool execution, session events, and lifecycle hooks

See docs/BLUMA_DEVELOPER_GUIDE.md for plugin development.

🔌 MCP Support

Model Context Protocol: Connect to external MCP servers
Resource listing: Discover and read MCP resources
SSE transport: Server-Sent Events for real-time communication

🧵 Thread Management

Thread lifecycle: Create, resume, fork, rename, archive, delete threads
Thread stats: View thread metadata and statistics
Codex-style interface: Familiar thread management commands

🦀 Native Modules (Rust)

High-performance native extensions for critical operations:

bluma-clipboard: Cross-platform clipboard with image support
- Built with Rust (arboard crate)
- No dependencies on wl-paste/xclip
- Native image reading for terminal paste
yoga-layout: High-performance layout engine for Ink
- Facebook's Yoga layout library
- Optimized for terminal UI rendering

📦 VS Code Extension

Full BluMa capabilities integrated into VS Code:

Chat Panel: Interactive chat interface with full BluMa capabilities
Session Sync: Real-time synchronization with terminal sessions
Image Support: Paste and view images directly in VS Code
File Integration: Open and edit files from within the chat
Streaming: Real-time response streaming with markdown rendering

See vscode-extension/README.md for setup instructions.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      BluMa CLI (Ink UI)                     │
├─────────────────────────────────────────────────────────────┤
│  BlumaShell  │  BlumaViewport  │  BlumaTranscript          │
│  BlumaBottomDock  │  BlumaWorkersOverlay  │  PlanPopup      │
├─────────────────────────────────────────────────────────────┤
│              useBlumaSessionRuntime (Hook)                  │
├─────────────────────────────────────────────────────────────┤
│  Session Registry  │  Agent Core  │  Tool Invoker          │
│  Thread Manager  │  Prompt Builder  │  Mailbox IPC         │
├─────────────────────────────────────────────────────────────┤
│  Native Tools (45+)  │  Skills (6)  │  MCP Clients         │
│  FactorAI Sandbox  │  Hook Registry  │  Feature Flags      │
└─────────────────────────────────────────────────────────────┘

Modular Tool Architecture

Each tool in src/app/agent/tools/ follows a consistent structure:

ToolName/
├── index.ts           # Public API exports
├── ToolName.ts        # Core implementation logic
├── UI.tsx             # React/Ink UI component
└── types.ts           # Type definitions

This modular design enables:

Independent testing of each tool
Clear separation of logic and presentation
Easy discovery and maintenance
Consistent patterns across the codebase

Core Components

src/main.ts: Entry point with CLI mode, agent mode, session management
src/app/ui/: React/Ink UI components
- App.tsx: Main orchestrator
- BlumaSession.tsx: Session management and UI lifecycle
- components/: Reusable UI elements (40+ components)
- hooks/: React hooks for state management
- theme/: Theme system and terminal styling
- utils/: Utility functions and slash command registry
src/app/agent/: AI agent core
- core/: Prompt building, context management, LLM integration, thread management
- tools/: Modular tool architecture — 43+ tool directories, each with:
  - Implementation logic (*.ts)
  - UI components (UI.tsx)
  - Type definitions (types.ts)
  - Index exports (index.ts)
- runtime/: Session runtime, sandbox policy, plugin system, hook registry
- session_manager/: Multi-session orchestration
- subagents/: Worker system with base LLM subagent and coordinator tools
- bluma/: BluMa-specific core logic and turn start payload
src/app/agent/config/: Configuration files and skill definitions
src/ink/: Ink renderer shims and compatibility layer
src/shims/: Build-time shims for react-compiler-runtime and bidi-js
native/: Rust-based native modules (clipboard, yoga-layout)
- bluma-clipboard: Cross-platform clipboard with image support
- yoga-layout: High-performance layout engine for Ink
vscode-extension/: VS Code extension for chat integration
- Chat panel with full BluMa capabilities
- Real-time session sync
- Image and file support

📋 Configuration

Environment Variables

Create a .env file in your project root:

# Required for AI features
FACTOR_ROUTER_KEY=your_key
FACTOR_ROUTER_URL=https://api.factorai.sh

# Optional: MCP Server
MCP_SSE_URL=http://localhost:3000/sse

# Optional: FactorAI Sandbox
FACTORAI_BASE_URL=http://localhost:8080
FACTORAI_API_KEY=your-sandbox-key

Runtime Modes

BluMa supports different permission modes:

Local Mode: Auto-approve safe operations
Sandbox Mode: Require confirmation for write/execute operations

Set via environment or runtime config:

BLUMA_PERMISSION_MODE=sandbox

🛠️ Development

Prerequisites

Node.js >= 20
npm >= 9

Setup

# Clone the repository
git clone https://github.com/Nomad-e/bluma-cli.git
cd bluma-cli

# Install dependencies
npm install

# Build the project
npm run build

# Start BluMa
npm start

Scripts

| Script | Description | |--------|-------------| | npm run build | TypeScript check + bundle | | npm run build:native | Build native modules | | npm run build:all | Build native + TypeScript | | npm run precommit | Run pre-commit validation | | npm start | Build + run BluMa | | npm test | Run Jest tests | | npm run test:watch | Watch mode for tests | | npm run test:parallel | Parallel test execution | | npm run test:parallel:fast | Fast parallel tests with 8 workers | | npm run lint | ESLint check | | npm run lint:fix | Auto-fix lint errors |

Testing

# Run all tests
npm test

# Run specific test file
npm test -- tests/tool_invocation.spec.ts

# Watch mode
npm run test:watch

# Parallel tests (faster)
npm run test:parallel:fast

Contributing

See CONTRIBUTING.md for detailed contribution guidelines.

📚 Documentation

Developer Guide: Complete technical reference
Skills Guide: How to create and use skills
Mailbox IPC: Multi-agent communication
CI/CD: Continuous integration setup
Message Queue: IPC system design
Parallel Tests: Test parallelization guide

🎯 Use Cases

1. Code Analysis & Refactoring

# Ask BluMa to analyze your codebase
bluma

# Then use slash commands
/explain src/app/agent/core/prompt_builder.ts
/refactor src/utils/helpers.ts
/fix src/components/Button.tsx

2. Multi-Agent Development

# Coordinator mode: delegate to workers
"Build a new feature with research, implementation, and verification"

# BluMa automatically spawns:
# - Researcher: Investigate codebase structure
# - Implementer: Write the code
# - Verifier: Run tests and validate

3. Release Engineering

/release patch          # Auto-detect version bump
/release minor --dry-run  # Preview release

4. Pull Request Creation

/pr "feat: add new authentication"  # Create PR with conventional commit

5. Web Integration

# Use the embeddable React chat widget
import { useChatWidget } from '@nomad-e/bluma-cli/chat-widget';

// Embed BluMa capabilities in your web app
const { messages, streamResponse } = useChatWidget();

6. VS Code Integration

# Install the VS Code extension
# Access full BluMa capabilities from within VS Code
- Chat panel with session sync
- Image and file support
- Real-time streaming

📄 License

Apache 2.0 — see LICENSE for details.

👤 Author

Alex Fonseca — @nomad-e

📰 Changelog

See CHANGELOG.md for detailed release notes.

What's New in v0.6.4 (2026-05-10)

Major Changes:

Circular Dependency Resolution: Fixed 'getNativeToolMetadata is not defined' error in tool metadata
Enhanced Native Tool Metadata: Improved tool descriptions and metadata clarity across all 45+ tools
Improved Multi-Agent Coordination: Better coordinator-worker communication and task tracking
Permission Mode Enhancement: Full mode enabled for auto-approve of all tools

Improvements:

Streamlined tool guidance in prompts
Better error handling and user-friendly error messages
Enhanced session persistence on LLM errors
Improved worker registration for UI visibility

Fixes:

Resolved circular dependency in tool metadata (prompt → tools → prompt cycle)
Fixed worker registration for UI visibility in task_boundary tracking
Improved session persistence on LLM errors

What's New in v0.6.2 (2026-05-09)

Major Features:

Modular Tool Architecture: All 45+ tools now have dedicated directories with separate logic, UI, and types
Native Clipboard Support: Rust-based clipboard implementation for cross-platform image handling
Thread Management: Full thread lifecycle with create, resume, fork, rename, archive, delete operations
Enhanced Multi-Agent Orchestration: Improved coordinator-worker communication with bidirectional mailbox IPC
Chat Widget: Embeddable React chat component for web integration