@nomad-e/bluma-cli

BluMa CLI — AI-Powered Agent for Advanced Software Engineering

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.

🚀 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 communication between coordinator and workers via send_message, list_mailbox_messages, poll_mailbox, signal_mailbox
• Worker Types: Researchers, implementers, verifiers with specialized roles
• Session Registry: Track and manage agent sessions with lifecycle events

📝 Slash Commands (80+ commands)

Quick access to common operations across 5 categories:

• Session (25+): /clear, /sessions, /attach, /follow, /bridge, /status, /logs, /resume, /kill, /compact, /export, /summarize, /history, /share, /copy, /commit, /pr, /release, /snip, /collapse, /brief, /undo, /redo, /thread (with subcommands: list/new/resume/fork/rename/archive/delete)
• Inspect (30+): /plugins, /plugin, /diagnostics, /permissions, /features, /hooks, /model, /effort, /style, /sandbox, /worktree, /statusline, /skills, /tools, /mcp, /debug-workers, /cost, /memory, /stats, /theme, /keybindings, /vim, /ctx, /dream, /diff, /editor, /config, /file, /search, /context, /token, /settings, /alias, /macro, /thread stats
• Agent (15+): /agent, /agents, /img, /image, /init, /review, /explain, /fix, /debug, /bug, /test, /optimize, /refactor, /document, /chat, /code, /terminal, /template
• Help: /help
• Input: 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

Extendable expertise modules with progressive disclosure:

• git-commit: Conventional commits automation with BluMa watermark
• git-pr: Pull request creation and management
• git-release: Full release engineering workflow (version bumps, changelog, tags, npm publish)
• pdf: PDF generation and manipulation (reports, merge, forms, OCR)
• xlsx: Spreadsheet processing (create, edit, formulas, charting, cleaning)
• skill-creator: Create custom 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

🔌 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

🏗️ 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)
• vscode-extension/: VS Code extension for chat integration

📋 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

📄 License

Apache 2.0 — see LICENSE for details.

👤 Author

Alex Fonseca — @nomad-e

BluMa CLI v0.3.1 — Built with TypeScript, React/Ink, and ES modules.