@nomad-e/bluma-cli
Advanced tools
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.
# 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
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_searchview_file_outline, edit_tool, file_write, notebook_edit, lsp_queryExecution (6 tools):
shell_command, command_status, send_command_input, kill_commandrepl (interactive code execution for Python/Node/Bash)task_output (real-time output following)Communication (7 tools):
message, ask_user_question, brief, send_messagelist_mailbox_messages, poll_mailbox, signal_mailboxPlanning (11 tools):
todo, task_boundary, task_create, task_update, task_stoptask_list, task_get, enter_plan_mode, exit_plan_modecron_create, cron_list, cron_deleteKnowledge (10 tools):
search_web, web_fetch, load_skill, coding_memoryctx_inspect, dream, context_collapse, sniplist_mcp_resources, read_mcp_resourceAgent Coordination (4 tools):
spawn_agent, wait_agent, list_agents, kill_agentFactorAI Sandbox (5 tools):
factorai.sh.create_next_app, factorai.sh.deploy_appfactorai.sh.get_app_status, factorai.sh.apply_app_changesfactorai.sh.redeploy_app~/.bluma/mailboxes/{session_id}.in/out/sig (JSONL format)task_boundary to track orchestration phases (PLANNING, EXECUTION, VERIFICATION)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 statisticsAgent 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 templateInput Methods:
Ctrl+V / Cmd+V - Paste image/text/fileCtrl+Shift+I - Same as Ctrl+Vcoding_memory)ctx_inspectStructured problem-solving workflow with 3 phases:
Extendable expertise modules with progressive disclosure — load only when needed:
Available Skills:
How Skills Work:
dist/config/skills/, {cwd}/.bluma/skills/, ~/.bluma/skills/Create Custom Skills: See docs/SKILLS.md for complete guide on authoring skills.
rm -rf protection, sudo blocking, dangerous command detectionExtensible architecture with hook registry and plugin system:
See docs/BLUMA_DEVELOPER_GUIDE.md for plugin development.
High-performance native extensions for critical operations:
Full BluMa capabilities integrated into VS Code:
See vscode-extension/README.md for setup instructions.
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────┘
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:
src/main.ts: Entry point with CLI mode, agent mode, session managementsrc/app/ui/: React/Ink UI components
App.tsx: Main orchestratorBlumaSession.tsx: Session management and UI lifecyclecomponents/: Reusable UI elements (40+ components)hooks/: React hooks for state managementtheme/: Theme system and terminal stylingutils/: Utility functions and slash command registrysrc/app/agent/: AI agent core
core/: Prompt building, context management, LLM integration, thread managementtools/: Modular tool architecture — 43+ tool directories, each with:
*.ts)UI.tsx)types.ts)index.ts)runtime/: Session runtime, sandbox policy, plugin system, hook registrysession_manager/: Multi-session orchestrationsubagents/: Worker system with base LLM subagent and coordinator toolsbluma/: BluMa-specific core logic and turn start payloadsrc/app/agent/config/: Configuration files and skill definitionssrc/ink/: Ink renderer shims and compatibility layersrc/shims/: Build-time shims for react-compiler-runtime and bidi-jsnative/: Rust-based native modules (clipboard, yoga-layout)
vscode-extension/: VS Code extension for chat integration
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
BluMa supports different permission modes:
Set via environment or runtime config:
BLUMA_PERMISSION_MODE=sandbox
# 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
| 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 |
# 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
See CONTRIBUTING.md for detailed contribution guidelines.
# 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
# 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
/release patch # Auto-detect version bump
/release minor --dry-run # Preview release
/pr "feat: add new authentication" # Create PR with conventional commit
# 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();
# 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
Apache 2.0 — see LICENSE for details.
Alex Fonseca — @nomad-e
See CHANGELOG.md for detailed release notes.
Major Changes:
Improvements:
Fixes:
Major Features:
Improvements:
Fixes:
BluMa CLI v0.6.4 — Built with TypeScript, React 19, Ink, and ES modules.
FAQs
BluMa independent agent for automation and advanced software engineering.
The npm package @nomad-e/bluma-cli receives a total of 413 weekly downloads. As such, @nomad-e/bluma-cli popularity was classified as not popular.
We found that @nomad-e/bluma-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
npm confirmed a tooling bug incorrectly marked several one-character packages as security holders and said it was working on a rollback.
Research
/Security News
Newer packages in this compromise use native extensions and .pth loaders to execute JavaScript stealers in developer environments.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.