BluMa CLI — Base Language Unit · Model Agent

BluMa is a CLI-based model agent for advanced software engineering workflows. Built with React/Ink 5, it provides an interactive terminal interface for LLM-powered automation, code generation, refactoring, and task execution. Features persistent sessions, contextual reasoning, smart feedback, coordinator mode for worker orchestration, and extensible tools/skills architecture.

Credit: BluMa was conceived and architected by Alex Fonseca.

Current Version: 0.1.84

Table of Contents

• Overview
• Key Features
• Requirements
• Installation
• Quick Start
• Configuration
• Architecture
• Native Tools
• Skills System
• Runtime & Orchestration
• Slash Commands
• Development
• Testing
• Contributing
• License

Overview

BluMa operates as a conversational agent in the terminal, combining:

• Rich UI Layer: React/Ink 5 components for interactive prompts, live overlays, and real-time feedback
• Agent Layer: LLM orchestration via FactorRouter with tool invocation and context management
• Runtime Layer: Task tracking, plugin system, hooks, diagnostics, session management, and coordinator mode
• Tool Layer: 50+ native tools + MCP SDK integration for external tools

The agent maintains persistent conversation history, workspace snapshots, and coding memory across sessions.

Key Features

Core Agent

• Interactive CLI: Rich terminal UI with React/Ink 5
• Session Persistence: Automatic save/load of conversation and tool history
• Context Management: Token-aware context compression with history anchoring
• Smart Feedback: Technical suggestions and automated checks
• Confirmation System: Controlled execution with whitelists and previews
• Coding Memory: Persistent notes about codebase decisions (~/.bluma/coding_memory.json)

Runtime & Orchestration (v0.1.41+)

• Plugin System: Load plugins from .bluma/plugins/ or ~/.bluma/plugins/
• Hook Registry: Event-driven lifecycle tracking (tool calls, decisions, state changes)
• Task Store: Persistent task management with PLANNING → EXECUTION → VERIFICATION flow
• Session Registry: Multi-session support with process health monitoring
• Thread System: Multi-thread conversation management with isolated contexts
• Diagnostics: Real-time system snapshot (tasks, hooks, plugins, sessions)
• Tool Execution Policy: Intelligent decisions based on sandbox mode and safety

Tools & Skills

• 50+ Native Tools: File operations, search, shell commands, web fetch, agent coordination, task management, MCP resources, cron scheduling, LSP queries, notebook editing, REPL execution
• Coordinator Mode: Orchestrator playbook for delegating work to background workers
• MCP Integration: Model Context Protocol SDK for external tool servers
• Skills System: Pluggable knowledge modules (git, PDF, Excel, etc.)
• Agent Coordination: Spawn/wait/list subagents for parallel work with bidirectional mailbox system

UI Components

• Slash Commands: 30+ built-in commands (/help, /model, /tasks, /plugins, /threads, etc.)
• Live Overlays: Working timers, progress indicators, streaming text
• Diff Previews: Side-by-side code comparisons before edits
• Tool Result Cards: Structured display of tool outputs
• Session Panels: Real-time monitoring with log streaming
• Thread Management: Multi-thread conversation UI with thread switching

Requirements

• Node.js: >= 20
• npm: >= 9
• FactorRouter: API key and URL for LLM backend

Installation

Global Installation (Recommended)

npm install -g @nomad-e/bluma-cli

Linux/macOS (if permission errors):

sudo npm install -g @nomad-e/bluma-cli

macOS Note: After installation, run bluma without sudo to avoid permission issues.

Local Development

git clone <repository-url>
cd bluma-cli
npm install
npm run build

Environment Setup

Set these environment variables globally:

# Linux/macOS: Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile
export FACTOR_ROUTER_KEY="sk-fai-your-key-here"
export FACTOR_ROUTER_URL="http://host:8003/router-api"

# Then reload
source ~/.bashrc  # or ~/.zshrc

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_KEY", "sk-fai-your-key-here", "User")
[Environment]::SetEnvironmentVariable("FACTOR_ROUTER_URL", "http://host:8003/router-api", "User")

Quick Start

# Launch BluMa
bluma

# Or from local development
npm start

First Interaction

> help me create a React component
> find all files containing "useEffect"
> run npm test in the background
> /tasks to see active tasks
> /model to switch LLM model
> /threads to manage conversation threads

Configuration

Runtime Settings (~/.bluma/settings.json)

{
  "model": "auto",
  "reasoningEffort": "medium",
  "outputStyle": "concise",
  "sandboxMode": "confirm",
  "alwaysAcceptTools": ["read_file_lines", "grep_search"],
  "theme": "default"
}

| Setting | Values | Description | |---------|--------|-------------| | model | auto | LLM model (FactorRouter decides) | | reasoningEffort | low, medium, high | Reasoning depth | | outputStyle | concise, balanced, verbose | Response style | | sandboxMode | confirm, auto, strict | Tool execution policy |

Directory Structure

~/.bluma/
├── settings.json          # Runtime configuration
├── coding_memory.json     # Persistent coding notes
├── artifacts/             # Saved plans and documents
├── plugins/               # Global plugins
├── sessions/              # Session history
└── threads/               # Thread storage

Architecture

┌─────────────────────────────────────────────────────────────┐
│                         UI Layer                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │  Bluma   │ │  Input   │ │  Slash   │ │  ToolResult  │   │
│  │ Session  │ │  Prompt  │ │ Commands │ │   Display    │   │
│  │  (Ink)   │ │          │ │          │ │              │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘   │
│       │            │            │              │            │
│  ┌────┴────────────┴────────────┴──────────────┴─────┐     │
│  │              BlumaShell / BlumaViewport            │     │
│  │         BlumaTranscript / BlumaBottomDock          │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┼────────────────────────────────┐
│                   Agent Layer                              │
│  ┌──────────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │    Agent     │  │  BluMa   │  │   RouteManager       │  │
│  │  Orchestrator│  │  Core    │  │   (FactorRouter)     │  │
│  └──────┬───────┘  └────┬─────┘  └──────────┬───────────┘  │
│         │               │                    │              │
│  ┌──────┴───────┐  ┌────┴────┐  ┌───────────┴──────────┐  │
│  │ ToolInvoker  │  │  LLM    │  │   PromptBuilder      │  │
│  │              │  │ Client  │  │   + ContextManager   │  │
│  └──────────────┘  └─────────┘  └──────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Thread Manager / Thread Store           │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┼────────────────────────────────┐
│                   Runtime Layer                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │TaskStore │ │HookReg.  │ │PluginReg.│ │SessionReg.   │   │
│  │          │ │          │ │          │ │              │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │Sandbox   │ │ToolExec  │ │Diagnostics│ │SessionView  │   │
│  │Policy    │ │Policy    │ │           │ │             │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │Feature   │ │Plan Mode │ │Tool Auto │ │Tool Permission│  │
│  │Flags     │ │Session   │ │Approve   │ │Classifier    │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │Mailbox   │ │Worker    │ │Permission│ │Thread        │   │
│  │Registry  │ │Context   │ │Rules     │ │Manager       │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────┼────────────────────────────────┐
│                    Tools Layer                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Native Tools (50+)                      │  │
│  │  edit_tool, file_write, shell_command, grep_search,  │  │
│  │  spawn_agent, wait_agent, list_agents,               │  │
│  │  send_message, list_mailbox_messages, signal_mailbox,│  │
│  │  todo, task_boundary, task_create, task_list,        │  │
│  │  task_get, task_update, task_stop,                   │  │
│  │  coding_memory, search_web, web_fetch, load_skill,   │  │
│  │  message, ask_user_question, repl,                   │  │
│  │  list_mcp_resources, read_mcp_resource,              │  │
│  │  cron_create, cron_list, cron_delete,                │  │
│  │  lsp_query, notebook_edit,                           │  │
│  │  enter_plan_mode, exit_plan_mode, ...                │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              MCP SDK Integration                     │  │
│  │         External tool servers via MCP                │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Native Tools

BluMa includes 50+ built-in tools organized by category:

File Operations

| Tool | Description | |------|-------------| | edit_tool | Replace text in files (precise, multi-line, batch edits) | | file_write | Create/overwrite entire files | | read_file_lines | Read specific line ranges (up to 2000 lines) | | count_file_lines | Get file line count | | ls_tool | List directories with filtering and pagination | | find_by_name | Glob-based file search | | grep_search | Text/regex search across files | | view_file_outline | Show code structure (classes, functions, interfaces) | | notebook_edit | Edit Jupyter .ipynb files (cells operations) |

Shell & Commands

| Tool | Description | |------|-------------| | shell_command | Execute background commands | | command_status | Check command progress/output | | send_command_input | Send input to running commands' stdin | | kill_command | Terminate running commands |

Agent Coordination (v0.1.60+)

| Tool | Description | |------|-------------| | spawn_agent | Create background worker agents | | wait_agent | Wait for agent completion | | list_agents | List active/completed agents | | send_message | Send follow-up to running worker (continue without re-spawn) | | list_mailbox_messages | Read messages from workers (progress, permission requests) | | signal_mailbox | Send ack/nack/progress signals to workers | | poll_mailbox | Poll mailbox for new messages |

Task & Project Management

| Tool | Description | |------|-------------| | todo | Manage task lists | | task_boundary | Track task phases (PLANNING/EXECUTION/VERIFICATION) | | task_create | Create session-scoped tasks | | task_list | List all session tasks | | task_get | Get one task by id | | task_update | Update task fields | | task_stop | Cancel a task | | task_output | Read task output in real-time | | create_artifact | Save documents under <workspace>/.bluma/artifacts/<session>/ | | read_artifact | Read artifacts from the current session directory |

Thread Management (v0.1.84+)

| Tool | Description | |------|-------------| | thread_create | Create new conversation thread | | thread_list | List all threads | | thread_switch | Switch to different thread | | thread_archive | Archive a thread |

Knowledge & Research

| Tool | Description | |------|-------------| | search_web | Search programming solutions (Reddit, GitHub, StackOverflow) | | web_fetch | Fetch and analyze remote URLs | | load_skill | Activate domain-specific skills | | coding_memory | CRUD for persistent coding notes |

Communication & Interaction

| Tool | Description | |------|-------------| | message | Post user-visible chat (info/result types) | | ask_user_question | Ask multiple-choice questions in terminal |

MCP & Resources

| Tool | Description | |------|-------------| | list_mcp_resources | List resources from MCP servers | | read_mcp_resource | Read a resource URI from MCP server |

Scheduling

| Tool | Description | |------|-------------| | cron_create | Schedule one-shot or repeating reminders | | cron_list | List scheduled cron jobs | | cron_delete | Cancel scheduled job |

Development Tools

| Tool | Description | |------|-------------| | lsp_query | LSP go-to-definition or references (TS/JS) | | repl | Interactive code execution (Python, Node, Bash) |

Specialized

| Tool | Description | |------|-------------| | context_collapse | Collapse context window | | dream_engine | Auto-dream feature (coding memory consolidation) | | brief | Generate project brief | | ctx_inspect | Inspect current context | | snip | Code snippet management | | coordinator_tools | Coordinator mode utilities | | create-next-app | Scaffold Next.js project with shadcn/ui + Tailwind | | deploy-app | Deploy Next.js to Severino hosting |

Plan Mode

| Tool | Description | |------|-------------| | enter_plan_mode | Enter plan-only mode (edits require confirmation) | | exit_plan_mode | Leave plan mode |

Current Features

Thread System (v0.1.84+)

Multi-thread conversation management for isolated contexts:

// Create a new thread
thread_create({
  name: "Feature Implementation",
  context: "Working on authentication module"
})

// List all threads
thread_list()

// Switch between threads
thread_switch({ threadId: "thread-123" })

Key Benefits:

• Isolated contexts - Each thread maintains separate conversation history
• Parallel work - Work on multiple features simultaneously
• Context preservation - Switch without losing previous context
• Thread-specific memory - Coding memories scoped to threads

Mailbox System (Bidirectional Communication)

Push-based communication between coordinator and workers using EventEmitter:

// Coordinator sends follow-up to running worker
send_message({
  to: "worker-session-id",
  message: "Fix the null pointer in src/auth/validate.ts:42..."
})

// Coordinator reads messages from workers
list_mailbox_messages({
  from: "worker-session-id",
  type: "progress_update",
  unreadOnly: true
})

// Workers send progress/permission requests
signal_mailbox({
  sessionId: "coordinator-session-id",
  type: "progress",
  data: { percent: 50 }
})

Key Benefits:

• No polling needed - EventEmitter pushes messages instantly
• Permission requests - Workers can request permissions mid-execution
• Progress tracking - Real-time progress updates
• Follow-up commands - Continue workers without re-spawn

Permission System

Granular permission rules with allow/deny patterns:

// Check permission for tool invocation
permissionRulesEngine.checkPermission('edit_tool', {
  filepath: '/src/auth/validate.ts'
})
// Returns: 'allow' | 'deny' | 'ask'

// Add custom rule
permissionRulesEngine.addRule({
  type: 'allow',
  toolPattern: 'read_*',
  pathPattern: '**/*.md',
  scope: 'global'
})

Features:

• Tool patterns - Wildcard matching for tool names
• Path patterns - Glob-based file path matching
• Command patterns - Shell command pattern matching
• Scopes - global, workspace, session-level rules

Worker Context Isolation

AsyncLocalStorage-based context for in-process workers:

import { runWithWorkerContext, createWorkerContext } from './worker_context'

const ctx = createWorkerContext({
  workerType: 'research',
  name: 'auth-investigation'
})

await runWithWorkerContext(ctx, async () => {
  // Worker code runs with isolated context
  // Shares LLM/MCP clients but has unique context
})

REPL Tool

Interactive code execution for rapid prototyping:

repl({
  language: 'python',
  code: `
import pandas as pd
df = pd.DataFrame({'a': [1, 2, 3]})
print(df.sum())
  `,
  timeout: 30000
})

Supported languages: Python, Node.js, Bash

Context Auto-Compact

Automatic context compression with history anchoring:

• Budget: 240k tokens
• Trigger: 70% of budget (168k tokens)
• Strategy: Compress old turns, keep last 10 turns complete
• Anchor: System message with compressed summary

const { messages, newAnchor } = await createApiContextWindow(
  fullHistory,
  currentAnchor,
  compressedTurnSliceCount,
  llmService,
  userContext
)

Session Memory Extractor

Automatic memory extraction from conversations:

const memories = await memoryExtractor.extractMemoriesFromSession(messages)
// Returns: ExtractedMemory[] with type, content, confidence, tags

// Get relevant memories for query
const relevant = await memoryExtractor.getRelevantMemories('authentication')

Memory types: codebase_knowledge, preference, decision, pattern, bugfix, architecture

Vim Mode

Vim-like keybindings in input prompt:

• Modes: normal, insert, visual, command
• Motions: h/j/k/l, w/b, 0/$, g/G
• Operators: d (delete), c (change), y (yank)
• Commands: :w, :q, etc.

// Enable vim mode
/vim toggle

Themes System

6 configurable UI themes:

| Theme | Description | |-------|-------------| | default | Classic dark terminal | | dracula | Purple accents | | github | GitHub Dark mode | | monokai | Vibrant green accents | | nord | Arctic blue palette | | tokyo | Tokyo Night blue-purple |

/theme dracula

Init Subagent

Automatic BluMa.md generation:

/init

Scans repository and generates comprehensive codebase documentation including:

• Project overview
• Technology stack detection
• Directory structure with annotations
• Key configs and scripts
• CLI commands
• Operational notes

Coding Memory Consolidate

Deduplication of coding memories:

consolidateCodingMemoryFile()
// Merges duplicate entries by normalized text
// Keeps oldest ID, merges tags
// Creates backup .bak file

Skills System

Skills are self-contained knowledge modules that extend BluMa with domain expertise. They use Progressive Disclosure to manage context efficiently.

Skill Sources (Priority Order)

| Priority | Source | Path | |----------|--------|------| | 1 | Bundled | dist/config/skills/ | | 2 | Project | {cwd}/.bluma/skills/ | | 3 | Global | ~/.bluma/skills/ |

Progressive Disclosure Levels

Level 1: description (frontmatter)
    Always visible. Cost: ~1 line per skill.
    Purpose: Let agent DECIDE to activate.
    
    ↓ agent calls load_skill(name)
    
Level 2: SKILL.md body
    Injected when activated. Cost: 50-300 lines.
    Purpose: Core instructions and quick-start.
    
    ↓ agent reads reference or runs script (if needed)
    
Level 3a: references/*.md
    Read on-demand. Cost: only when read.
    Purpose: Advanced documentation.
    
Level 3b: scripts/*.py
    Executed on-demand. Cost: zero context.
    Purpose: Pre-built utilities.

Available Skills

| Skill | Description | |-------|-------------| | git-commit | Conventional commits, staging, commit messages | | git-pr | Pull requests, code review preparation | | git-release | Version bumps, changelogs, git tags, GitHub releases | | pdf | PDF creation, extraction, merging, OCR | | xlsx | Spreadsheet operations, formulas, charts | | skill-creator | Author new BluMa skills |

Loading Skills

// Via command
> load the git-commit skill

// Via tool call
load_skill({ skill_name: "git-commit" })

Skills inject domain knowledge and best practices into the agent's context. Each skill has:

• Frontmatter: Description and dependencies (always visible)
• Body: Core instructions (injected on activation)
• References: Advanced docs (read on-demand)
• Scripts: Executable utilities (zero context cost)

Runtime & Orchestration

Task Store

Track work with PLANNING → EXECUTION → VERIFICATION phases:

task_boundary({
  task_name: "Implementing Authentication",
  mode: "PLANNING",
  task_status: "Creating middleware structure"
});

Thread Manager (v0.1.84+)

Manage multiple conversation threads:

// Thread operations
thread_create({ name: "Feature A" })
thread_list()
thread_switch({ threadId: "..." })
thread_archive({ threadId: "..." })

Hook Registry

Event-driven lifecycle tracking:

// Hooks fire on: tool_calls, decisions, state_changes
registerHook('tool_calls', (event) => {
  console.log(`Tool ${event.toolName} executed`);
});

Plugin Registry

Load plugins from .bluma/plugins/:

> /plugins list          # Show loaded plugins
> /plugins load my-plugin # Load a plugin

Session Registry

Multi-session support with health monitoring:

> /sessions list         # List all sessions
> /sessions logs <id>    # Stream session logs
> /sessions kill <id>    # Terminate session

Diagnostics

Real-time system snapshot:

> /diagnostics           # Full system status
> /diagnostics tasks     # Task overview
> /diagnostics hooks     # Hook registry status
> /diagnostics plugins   # Plugin registry status
> /diagnostics sessions  # Active sessions
> /diagnostics threads   # Thread overview

Runtime Files

| File | Purpose | |------|---------| | ~/.bluma/task_state.json | Persistent task tracking | | ~/.bluma/hooks.json | Hook registry state | | ~/.bluma/sessions/ | Session history and logs | | ~/.bluma/plugins/ | Global plugin storage | | ~/.bluma/threads/ | Thread storage |

Tool Execution Policy

BluMa uses intelligent tool execution based on sandbox mode:

| Sandbox Mode | Behavior | |--------------|----------| | confirm | Prompt for dangerous tools (shell, edit, write) | | auto | Auto-approve safe tools, confirm risky ones | | strict | Require confirmation for all tools |

Safe tools (always auto-approved): read_file_lines, grep_search, ls_tool, find_by_name, count_file_lines, view_file_outline

Slash Commands

Built-in terminal commands (type / to see all):

Session & UI

| Command | Description | |---------|-------------| | /clear | Clear chat below welcome panel | | /sessions | Show registered sessions (current + historical) | | /attach <id> | Live-follow a session log stream | | /follow <id> | Alias of /attach for live session follow | | /bridge | Show session bridge state and follow instructions | | /status <id> | Show session status for a session id | | /logs <id> | Show recent logs for a session id | | /resume <id> | Resume a session from the current CLI | | /kill <id> | Send SIGTERM to a session by id | | /tasks [list\|add\|complete\|update\|remove\|clear] | Manage task list | | /plan [show\|start\|end] | Manage the active task boundary | | /compact | Manually compact conversation context | | /export | Export conversation as markdown |

Threads (v0.1.84+)

| Command | Description | |---------|-------------| | /threads | List all conversation threads | | /thread [id] | Switch to thread or show current | | /thread new [name] | Create new thread | | /thread archive [id] | Archive a thread |

Agent

| Command | Description | |---------|-------------| | /img ./shot.png [question] | Send local image(s) to the model | | /image | Alias of /img | | /init | Run init subagent — BluMa.md codebase documentation | | /agent [default\|coordinator] | Set prompt profile (coordinator playbook for worker orchestration) | | /agents | List worker/agent sessions (spawn_agent children) |

Inspect

| Command | Description | |---------|-------------| | /plugins | List installed plugins and plugin paths | | /plugin <name> | Inspect one plugin | | /diagnostics | Show a consolidated health snapshot | | /permissions | Inspect sandbox and tool rules; set mode | | /hooks | Inspect, enable, disable, or clear lifecycle hooks | | /model [list\|name\|auto] | Show, list, or set the active model | | /effort [low\|medium\|high] | Show or set reasoning effort | | /style [default\|compact\|brief] | Show or set output style | | /sandbox [on\|off] | Show or toggle sandbox mode | | /worktree [path] | Show or set workspace root | | /statusline | Show the current session statusline summary | | /skills | List load_skill modules, dirs, and conflicts | | /tools [grep] | List native tools (optional filter) | | /mcp [fs] | List MCP tools (optional filter) | | /features | Feature flags: /features or /features <key> on\|off | | /debug-workers | Show running workers, PIDs, memory, and event bus state | | /cost | Show session cost and token usage | | /memory | Manage session memories | | /stats | Detailed session statistics | | /theme | Change UI theme | | /keybindings | Show or configure keybindings | | /vim | Toggle vim mode |

Help

| Command | Description | |---------|-------------| | /help | List all slash commands (grouped) |

Input (Keyboard Shortcuts)

| Shortcut | Description | |----------|-------------| | Ctrl+V / Cmd+V | Paste from clipboard: image → cache ~/.cache/bluma/clipboard; text; or file path as image | | Ctrl+Shift+I | Same as Ctrl+V (paste image, text, or file path) | | Ctrl+O | Expand truncated previews in tool results |

Development

Build

npm run build        # Production build
npm run build:native # Build native modules
npm run build:all    # Build native + main
npm start           # Build + run

Lint

npm run lint        # Check code style
npm run lint:fix    # Auto-fix issues

Test

npm test            # Run all tests
npm run test:watch  # Watch mode
npm run test:parallel        # Parallel test execution
npm run test:parallel:fast   # Fast parallel with 8 workers

Project Structure

src/
├── app/
│   ├── agent/
│   │   ├── agent.ts                    # Main orchestrator
│   │   ├── bluma/                      # Core agent logic
│   │   │   ├── core/
│   │   │   │   ├── bluma.ts            # BluMaAgent class
│   │   │   │   └── turn_start_payload.ts
│   │   │   ├── context/
│   │   │   │   └── auto_compact.ts     # Automatic context compaction
│   │   │   ├── memory/
│   │   │   │   └── session_memory.ts   # Session memory
│   │   │   └── types/
│   │   │       └── errors.ts           # Error type definitions
│   │   ├── config/
│   │   │   ├── native_tools.json       # Tool definitions (50+)
│   │   │   ├── skills/                 # Bundled skills
│   │   │   │   ├── git-commit/
│   │   │   │   ├── git-pr/
│   │   │   │   ├── git-release/        # Version bumps, changelogs, releases
│   │   │   │   ├── pdf/
│   │   │   │   ├── skill-creator/
│   │   │   │   └── xlsx/
│   │   │   │       └── scripts/
│   │   │   │           └── office/     # Office document handling
│   │   ├── core/                       # LLM, context, prompts
│   │   │   ├── context-api/            # Context management
│   │   │   │   ├── context_manager.ts  # Token-aware context
│   │   │   │   ├── history_anchor.ts   # Conversation anchoring
│   │   │   │   └── token_counter.ts    # Tiktoken integration
│   │   │   ├── llm/                    # LLM client
│   │   │   │   ├── llm.ts              # FactorRouter client
│   │   │   │   ├── llm_errors.ts       # LLM error formatting
│   │   │   │   ├── streaming_delta.ts  # Streaming delta handling
│   │   │   │   └── tool_call_normalizer.ts
│   │   │   ├── prompt/                 # Prompt engineering
│   │   │   │   ├── prompt_builder.ts   # Dynamic prompts
│   │   │   │   ├── workspace_snapshot.ts
│   │   │   │   ├── mcp_instructions.ts
│   │   │   │   ├── model_info.ts
│   │   │   │   ├── production_sandbox_prompt.ts
│   │   │   │   ├── system_prompt_sections.ts
│   │   │   │   ├── system_reminders.ts
│   │   │   │   └── tool_guidance.ts
│   │   │   ├── thread/                 # Thread management (v0.1.84+)
│   │   │   │   ├── index.ts
│   │   │   │   ├── thread_manager.ts
│   │   │   │   ├── thread_store.ts
│   │   │   │   └── types.ts
│   │   │   └── context_viz.ts          # Context visualization
│   │   ├── docs/
│   │   │   └── TOOL_PARITY.md          # Tool parity documentation
│   │   ├── feedback/
│   │   │   └── feedback_system.ts      # Smart feedback system
│   │   │   └── feedback_scoring.ts     # User feedback scoring
│   │   ├── runtime/                    # Orchestration layer
│   │   │   ├── diagnostics.ts          # System snapshots
│   │   │   ├── feature_flags.ts        # Feature gates
│   │   │   ├── hook_registry.ts        # Event-driven hooks
│   │   │   ├── native_tool_catalog.ts  # Tool registry
│   │   │   ├── permission_bridge.ts    # Leader↔Worker permission system
│   │   │   ├── permission_rules.ts     # Permission rule definitions
│   │   │   ├── tool_permission_classifier.ts
│   │   │   ├── plan_mode_session.ts    # Plan mode state
│   │   │   ├── plugin_registry.ts      # Plugin system
│   │   │   ├── plugin_runtime.ts       # Plugin execution
│   │   │   ├── runtime_config.ts       # Runtime settings
│   │   │   ├── sandbox_policy.ts       # Safety policies
│   │   │   ├── session_registry.ts     # Multi-session mgmt
│   │   │   ├── session_view.ts         # Session monitoring
│   │   │   ├── task_store.ts           # Task lifecycle
│   │   │   ├── tool_auto_approve.ts    # Auto-approve rules
│   │   │   ├── tool_execution_policy.ts
│   │   │   ├── tool_orchestration.ts   # Parallel read eligibility
│   │   │   ├── mailbox_registry.ts     # Mailbox system
│   │   │   ├── worker_context.ts       # Worker context management
│   │   │   └── factorai_context.ts     # FactorAI app context
│   │   ├── session_manager/
│   │   │   └── session_manager.ts      # Session persistence
│   │   ├── skills/
│   │   │   └── skill_loader.ts         # 3-source skill loading
│   │   ├── subagents/                  # Subagent system
│   │   │   ├── base_llm_subagent.ts
│   │   │   ├── init/                   # Init subagent (BluMa.md)
│   │   │   │   ├── init_subagent.ts    # Deep project analysis
│   │   │   │   ├── init_system_prompt.ts
│   │   │   │   └── contracts.ts
│   │   │   ├── registry.ts
│   │   │   ├── subagents_bluma.ts      # SubAgent orchestration
│   │   │   ├── types.ts                # SubAgent type definitions
│   │   │   └── worker_system_prompt.ts
│   │   ├── tools/
│   │   │   ├── mcp/
│   │   │   │   └── mcp_client.ts       # MCP SDK client
│   │   │   ├── shared/
│   │   │   │   └── token_utils.ts      # Token utilities
│   │   │   └── natives/                # 50+ native tool implementations
│   │   │       ├── agent_coordination.ts
│   │   │       ├── ask_user_question.ts
│   │   │       ├── async_command.ts
│   │   │       ├── coding_memory.ts
│   │   │       ├── coding_memory_consolidate.ts
│   │   │       ├── coordinator_tools.ts
│   │   │       ├── count_lines.ts
│   │   │       ├── edit.ts
│   │   │       ├── file_write.ts
│   │   │       ├── find_by_name.ts
│   │   │       ├── grep_search.ts
│   │   │       ├── list_mailbox_messages.ts
│   │   │       ├── load_skill.ts
│   │   │       ├── ls.ts
│   │   │       ├── lsp_query.ts
│   │   │       ├── mcp_resources.ts
│   │   │       ├── message.ts
│   │   │       ├── notebook_edit.ts
│   │   │       ├── plan_mode_tools.ts
│   │   │       ├── poll_mailbox.ts
│   │   │       ├── readLines.ts
│   │   │       ├── repl.ts
│   │   │       ├── search_web.ts
│   │   │       ├── send_message.ts
│   │   │       ├── session_cron.ts
│   │   │       ├── shell_command.ts
│   │   │       ├── signal_mailbox.ts
│   │   │       ├── task_boundary.ts
│   │   │       ├── task_output.ts
│   │   │       ├── task_tools.ts
│   │   │       ├── todo.ts
│   │   │       ├── view_file_outline.ts
│   │   │       └── web_fetch.ts
│   │   ├── types/
│   │   │   └── index.ts
│   │   └── utils/
│   │       ├── blumamd.ts              # BluMa markdown utilities
│   │       ├── coordinator_prompt.ts   # Coordinator mode playbook
│   │       ├── logger.ts               # Logging utilities
│   │       ├── update_check.ts
│   │       └── user_message_images.ts
│   └── ui/
│       ├── App.tsx                     # Main UI component
│       ├── BlumaSession.tsx            # Session component (v0.1.84+)
│       ├── Asci/
│       │   └── AsciiArt.ts
│       ├── components/                 # 35+ UI components
│       │   ├── AnimatedBorder.tsx
│       │   ├── AskUserQuestionPrompt.tsx
│       │   ├── AssistantMessageDisplay.tsx
│       │   ├── BlumaBottomDock.tsx     # Bottom dock (v0.1.84+)
│       │   ├── BlumaShell.tsx          # Shell container (v0.1.84+)
│       │   ├── BlumaTranscript.tsx     # Message transcript (v0.1.84+)
│       │   ├── BlumaViewport.tsx       # Viewport container (v0.1.84+)
│       │   ├── BlumaWorkersOverlay.tsx # Workers overlay (v0.1.84+)
│       │   ├── CollapsibleResult.tsx
│       │   ├── ConfirmationPrompt.tsx  # Permission confirmation dialog
│       │   ├── CtrlOToExpand.tsx       # Ctrl+O expansion (v0.1.84+)
│       │   ├── EditToolDiffPanel.tsx   # Diff preview for edits
│       │   ├── ErrorMessage.tsx
│       │   ├── ExpandedPreviewBlock.tsx
│       │   ├── FilePathLink.tsx        # File path links (v0.1.84+)
│       │   ├── HighlightedCode.tsx     # Syntax highlighting (v0.1.84+)
│       │   ├── InputPrompt.tsx         # User input
│       │   ├── InteractiveMenu.tsx     # Interactive menu component
│       │   ├── MarkdownRenderer.tsx
│       │   ├── ProgressBar.tsx
│       │   ├── ReasoningDisplay.tsx    # LLM reasoning
│       │   ├── SessionStats.tsx
│       │   ├── SimpleDiff.tsx
│       │   ├── SlashCommands.tsx       # 30+ commands
│       │   ├── StartupUpdateGate.tsx   # Update check gate
│       │   ├── StatusNotification.tsx
│       │   ├── StreamingText.tsx       # Live text output
│       │   ├── TaskDisplay.tsx
│       │   ├── TodoPlanDisplay.tsx     # Task visualization
│       │   ├── ToolCallDisplay.tsx
│       │   ├── ToolInvocationBlock.tsx
│       │   ├── ToolResultCard.tsx      # Structured results
│       │   ├── ToolResultDisplay.tsx
│       │   ├── TypewriterText.tsx
│       │   ├── UpdateNotice.tsx
│       │   ├── WorkerOverlay.tsx       # Worker status overlay
│       │   ├── WorkerStatusList.tsx    # Active workers list
│       │   ├── WorkerTranscript.tsx    # Worker conversation transcript
│       │   ├── WorkingTimer.tsx        # Work duration timer
│       │   ├── WorkingShimmerText.tsx  # Shimmer text effect
│       │   ├── streamingTextFlush.ts
│       │   ├── toolCallRenderers.tsx
│       │   └── slash-commands/         # Slash command renderers
│       │       ├── SessionLivePanel.tsx
│       │       ├── SlashCommands.types.ts
│       │       ├── commandHelpers.tsx
│       │       ├── constants.ts
│       │       └── renderers/
│       │           ├── index.ts
│       │           ├── configRenderers.tsx
│       │           ├── infoRenderers.tsx
│       │           ├── permissionRenderers.tsx
│       │           ├── pluginRenderers.tsx
│       │           ├── sessionRenderers.tsx
│       │           ├── staticRenderers.tsx
│       │           ├── taskRenderers.tsx
│       │           └── threadRenderers.tsx  # Thread renderers (v0.1.84+)
│       ├── constants/
│       │   ├── historyLayout.ts        # History layout constants
│       │   ├── inputPaste.ts           # Input paste constants
│       │   ├── toolUiPreview.ts        # Tool UI preview constants
│       │   └── toolUiSymbols.ts        # Tool UI symbols
│       ├── hooks/
│       │   ├── useAtCompletion.ts      # Completion hook
│       │   ├── useBlumaSessionRuntime.tsx  # Session runtime hook (v0.1.84+)
│       │   └── useWorkerProgress.ts    # Worker progress hook
│       ├── prompts/
│       │   └── initCommandPrompt.ts    # Init command prompt
│       ├── theme/
│       │   ├── blumaTerminal.ts
│       │   ├── themes.ts               # Theme definitions
│       │   └── m3Layout.tsx            # Material Design 3 layout
│       └── utils/
│           ├── clipboardImage.ts
│           ├── editToolDiffUtils.ts
│           ├── expandPreviewHotkey.ts
│           ├── expandablePreviewStore.ts
│           ├── formatTurnDurationMs.ts
│           ├── inlineImageInputLabels.ts
│           ├── pathDisplay.ts
│           ├── shellToolNames.ts
│           ├── slashRegistry.ts
│           ├── terminalTitle.ts        # Terminal title keeper
│           ├── toolActionLabels.ts     # Tool action labels
│           ├── toolDisplayLabels.ts    # Tool display labels
│           ├── toolInvocationPairing.ts
│           ├── toolResultStatusStore.ts
│           ├── update_message.ts
│           ├── useSimpleInputBuffer.ts
│           └── vim_engine.ts           # Vim mode engine
├── main.ts                             # Entry point
└── types/
    └── semver-functions.d.ts

Testing

npm test            # Run all tests
npm run test:watch  # Watch mode
npm run test:parallel        # Parallel execution
npm run test:parallel:fast   # Fast mode with 8 workers

Test Structure

tests/                    # 40+ test files
├── agent_*.spec.ts       # Agent routing, overlays, coordination
├── edit_tool.spec.ts     # File editing operations
├── file_write.spec.ts    # File write operations
├── sandbox_policy.spec.ts # Tool execution policies
├── task_runtime.integration.spec.ts # Task lifecycle
├── context_compression.integration.spec.ts # Context management
├── hook_registry.spec.ts # Hook system and event tracking
├── plugin_registry.spec.ts # Plugin loading and lifecycle
├── session_registry.spec.ts # Session management
├── session_manager.spec.ts # Session lifecycle
├── tool_execution_policy.spec.ts # Safe vs dangerous tool decisions
├── diagnostics.spec.ts   # System diagnostics
├── runtime_config.spec.ts # Runtime configuration
├── slash_routing.spec.ts # Slash command routing
├── subagents_flow.integration.spec.ts # Subagent coordination
├── prompt_builder.spec.ts # Prompt engineering
├── token_counter.spec.ts # Token counting
├── coding_memory.spec.ts # Persistent memory
├── web_fetch.spec.ts     # Web fetching
├── workspace_snapshot.spec.ts # Workspace analysis
├── ui_*.spec.ts(x)       # UI component tests
├── llm_stream_partial.spec.ts # LLM streaming partial handling
├── llm_errors.spec.ts    # LLM error handling
├── context_manager_sanitize.spec.ts # Context sanitization
├── coordinator-worker-mailbox.integration.spec.ts # Mailbox system
├── jest-resolver.cjs     # Jest resolver configuration
└── ...                   # Additional integration and unit tests

Contributing

See CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a branch: feat/add-feature or fix/bug-description
3. Make changes following the style guide
4. Add/update tests
5. Ensure build passes: npm run build && npm test
6. Open a Pull Request

Style Guide

• Use English for code, comments, and commits
• 2-space indentation
• TypeScript with modern React patterns
• Follow existing code structure

License

Apache 2.0 — see LICENSE for details.

Support

• Issues: GitHub Issues
• Documentation: This README + docs/ directory
• Author & Architect: Alex Fonseca (conceived and architected BluMa)
• npm Package: @nomad-e/bluma-cli

Runtime Modules

BluMa's runtime layer provides enterprise-grade orchestration:

| Module | Purpose | Key Features | |--------|---------|--------------| | task_store.ts | Task lifecycle | PLANNING → EXECUTION → VERIFICATION phases, persistence | | thread_manager.ts | Thread management | Multi-thread conversations, context isolation | | hook_registry.ts | Event system | Tool calls, decisions, state changes | | plugin_registry.ts | Plugin system | Load from .bluma/plugins/, lifecycle management | | session_registry.ts | Multi-session | Process health monitoring, session isolation | | mailbox_registry.ts | Communication | Bidirectional coordinator-worker messaging | | worker_context.ts | Worker isolation | AsyncLocalStorage-based context | | permission_rules.ts | Permissions | Granular allow/deny rules | | sandbox_policy.ts | Safety | Safe vs dangerous tool classification | | tool_execution_policy.ts | Execution rules | Auto-approve, confirm, block decisions | | diagnostics.ts | System snapshots | Tasks, hooks, plugins, sessions overview | | session_view.ts | Session monitoring | Log streaming, status display | | native_tool_catalog.ts | Tool registry | Discovery and metadata | | runtime_config.ts | Settings | Runtime configuration management | | feature_flags.ts | Feature gates | Opt-in features via env or settings | | plan_mode_session.ts | Plan mode | Forces confirmation for edits/writes | | tool_auto_approve.ts | Auto-approve | Effective approve rules | | tool_orchestration.ts | Parallel reads | Eligibility for parallel execution | | tool_permission_classifier | Tool classification | Classify tool invocations | | plugin_runtime.ts | Plugin execution | Plugin runtime context |

UI Components

Key UI components that power the rich terminal experience:

| Component | Purpose | |-----------|---------| | BlumaSession.tsx | Main session component with event handling | | BlumaShell.tsx | Shell container for layout | | BlumaViewport.tsx | Viewport container for responsive layout | | BlumaTranscript.tsx | Message transcript display | | BlumaBottomDock.tsx | Bottom dock for status and controls | | BlumaWorkersOverlay.tsx | Overlay for worker status | | EditToolDiffPanel.tsx | Side-by-side diff previews before edits | | ToolResultCard.tsx | Structured tool output display | | SlashCommands.tsx | Command palette and help | | StreamingText.tsx | Live text output with typing effects | | ReasoningDisplay.tsx | LLM reasoning visualization | | TodoPlanDisplay.tsx | Task list visualization | | SessionStats.tsx | Session metrics and status | | AnimatedBorder.tsx | Visual feedback for active elements | | CollapsibleResult.tsx | Expandable result sections | | ProgressBar.tsx | Progress indicators | | AskUserQuestionPrompt.tsx | Multiple-choice question UI | | ToolInvocationBlock.tsx | Tool call visualization | | AssistantMessageDisplay.tsx | Assistant message formatting | | CtrlOToExpand.tsx | Ctrl+O expansion for previews | | FilePathLink.tsx | Clickable file path links | | HighlightedCode.tsx | Syntax highlighted code blocks | | WorkingShimmerText.tsx | Shimmer text effect for loading states |