npm package: @nomad-e/bluma-cli
Description: BluMa independent agent for automation and advanced software engineering.
Author: Alex Fonseca
Latest version: 0.1.55

# BluMa CLI — Base Language Unit · Model Agent

[![npm version](https://img.shields.io/npm/v/@nomad-e/bluma-cli.svg?style=flat-square)](https://www.npmjs.com/package/@nomad-e/bluma-cli)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org/)

**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.

**Current Version:** 0.1.47

---

## Table of Contents

- [Overview](#overview)
- [Key Features](#key-features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Native Tools](#native-tools)
- [Skills System](#skills-system)
- [Runtime & Orchestration](#runtime--orchestration)
- [Slash Commands](#slash-commands)
- [Development](#development)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#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**: 40+ 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
- **Diagnostics**: Real-time system snapshot (tasks, hooks, plugins, sessions)
- **Tool Execution Policy**: Intelligent decisions based on sandbox mode and safety

### Tools & Skills
- **40+ Native Tools**: File operations, search, shell commands, web fetch, agent coordination, task management, MCP resources, cron scheduling, LSP queries, notebook editing
- **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

### UI Components
- **Slash Commands**: 20+ built-in commands (`/help`, `/model`, `/tasks`, `/plugins`, 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

---

## Requirements

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

---

## Installation

### Global Installation (Recommended)

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

**Linux/macOS** (if permission errors):
```bash
sudo npm install -g @nomad-e/bluma-cli
```

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

### Local Development

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

### Environment Setup

Set these environment variables globally:

```bash
# 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)**:
```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

```bash
# 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
```

---

## Configuration

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

```json
{
  "model": "gpt-4o",
  "reasoningEffort": "medium",
  "outputStyle": "concise",
  "sandboxMode": "confirm",
  "alwaysAcceptTools": ["read_file_lines", "grep_search"],
  "theme": "default"
}
```

| Setting | Values | Description |
|---------|--------|-------------|
| `model` | `gpt-4o`, `gpt-4o-mini`, `claude-sonnet-4-20250514` | LLM model |
| `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
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                         UI Layer                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │   App    │ │ Input    │ │ Slash    │ │  ToolResult  │   │
│  │  (Ink)   │ │ Prompt   │ │ Commands │ │   Display    │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘   │
└───────┼────────────┼────────────┼──────────────┼───────────┘
        │            │            │              │
        └────────────┴────────────┴──────────────┘
                         │
┌────────────────────────┼────────────────────────────────────┐
│                   Agent Layer                               │
│  ┌──────────────┐  ┌──────────┐  ┌──────────────────────┐  │
│  │    Agent     │  │  BluMa   │  │   RouteManager       │  │
│  │  Orchestrator│  │  Core    │  │   (FactorRouter)     │  │
│  └──────┬───────┘  └────┬─────┘  └──────────┬───────────┘  │
│         │               │                    │              │
│  ┌──────┴───────┐  ┌────┴────┐  ┌───────────┴──────────┐  │
│  │ ToolInvoker  │  │  LLM    │  │   PromptBuilder      │  │
│  │              │  │ Client  │  │   + ContextManager   │  │
│  └──────────────┘  └─────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                         │
┌────────────────────────┼────────────────────────────────────┐
│                   Runtime Layer                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │TaskStore │ │HookReg.  │ │PluginReg.│ │SessionReg.   │   │
│  │          │ │          │ │          │ │              │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │Sandbox   │ │ToolExec  │ │Diagnostics│ │SessionView  │   │
│  │Policy    │ │Policy    │ │           │ │             │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │Feature   │ │Plan Mode │ │Tool Auto │ │Tool Permission│  │
│  │Flags     │ │Session   │ │Approve   │ │Classifier    │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
                         │
┌────────────────────────┼────────────────────────────────────┐
│                    Tools Layer                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Native Tools (40+)                      │  │
│  │  edit_tool, file_write, shell_command, grep_search,  │  │
│  │  spawn_agent, wait_agent, list_agents,               │  │
│  │  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,                         │  │
│  │  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 **40+ 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
| Tool | Description |
|------|-------------|
| `spawn_agent` | Create background worker agents |
| `wait_agent` | Wait for agent completion |
| `list_agents` | List active/completed agents |

### 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 |
| `create_artifact` | Save documents to `~/.bluma/artifacts/` |
| `read_artifact` | Retrieve saved artifacts |

### 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) |

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

---

## 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 |
| `pdf` | PDF creation, extraction, merging, OCR |
| `xlsx` | Spreadsheet operations, formulas, charts |
| `skill-creator` | Author new BluMa skills |

### Loading Skills

```typescript
// 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:

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

### Hook Registry

Event-driven lifecycle tracking:

```typescript
// 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/`:

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

### Session Registry

Multi-session support with health monitoring:

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

### Diagnostics

Real-time system snapshot:

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

### 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 |

### 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 |

### 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` |

### 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) |

---

## Development

### Build

```bash
npm run build        # Production build
npm start           # Build + run
```

### Lint

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

### Project Structure

```
src/
├── app/
│   ├── agent/
│   │   ├── agent.ts                    # Main orchestrator
│   │   ├── bluma/                      # Core agent logic
│   │   │   ├── core/
│   │   │   │   └── bluma.ts            # BluMaAgent class
│   │   │   └── turn_start_payload.ts   # Backend turn payload
│   │   ├── config/
│   │   │   ├── native_tools.json       # Tool definitions (40+)
│   │   │   └── skills/                 # Bundled skills (git-commit, git-pr, pdf, xlsx, skill-creator)
│   │   ├── 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
│   │   │   │   └── tool_call_normalizer.ts
│   │   │   └── prompt/                 # Prompt engineering
│   │   │       ├── prompt_builder.ts   # Dynamic prompts
│   │   │       └── workspace_snapshot.ts
│   │   ├── feedback/
│   │   │   └── feedback_system.ts      # Smart feedback system
│   │   ├── runtime/                    # Orchestration layer (v0.1.41+)
│   │   │   ├── diagnostics.ts          # System snapshots
│   │   │   ├── feature_flags.ts        # Feature gates
│   │   │   ├── hook_registry.ts        # Event-driven hooks
│   │   │   ├── native_tool_catalog.ts  # Tool registry
│   │   │   ├── 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
│   │   │   └── tool_permission_classifier.ts
│   │   ├── session_manager/
│   │   │   └── session_manager.ts      # Session persistence
│   │   ├── skills/
│   │   │   └── skill_loader.ts         # Skill loading
│   │   ├── subagents/                  # Subagent system
│   │   │   ├── base_llm_subagent.ts
│   │   │   ├── init/                   # Init subagent (BluMa.md)
│   │   │   ├── registry.ts
│   │   │   ├── subagents_bluma.ts
│   │   │   └── types.ts
│   │   ├── tools/
│   │   │   ├── mcp/
│   │   │   │   └── mcp_client.ts       # MCP SDK client
│   │   │   └── natives/                # 27 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
│   │   │       ├── load_skill.ts
│   │   │       ├── ls.ts
│   │   │       ├── lsp_query.ts
│   │   │       ├── mcp_resources.ts
│   │   │       ├── message.ts
│   │   │       ├── notebook_edit.ts
│   │   │       ├── plan_mode_tools.ts
│   │   │       ├── readLines.ts
│   │   │       ├── search_web.ts
│   │   │       ├── session_cron.ts
│   │   │       ├── shell_command.ts
│   │   │       ├── task_boundary.ts
│   │   │       ├── task_tools.ts
│   │   │       ├── todo.ts
│   │   │       ├── view_file_outline.ts
│   │   │       └── web_fetch.ts
│   │   ├── types/
│   │   │   └── index.ts
│   │   └── utils/
│   │       ├── coordinator_prompt.ts   # Coordinator mode playbook
│   │       ├── update_check.ts
│   │       └── user_message_images.ts
│   └── ui/
│       ├── App.tsx                     # Main UI component
│       ├── Asci/
│       │   └── AsciiArt.ts
│       ├── components/                 # 24+ UI components
│       │   ├── AnimatedBorder.tsx
│       │   ├── AskUserQuestionPrompt.tsx
│       │   ├── AssistantMessageDisplay.tsx
│       │   ├── CollapsibleResult.tsx
│       │   ├── EditToolDiffPanel.tsx   # Diff preview for edits
│       │   ├── ErrorMessage.tsx
│       │   ├── ExpandedPreviewBlock.tsx
│       │   ├── InputPrompt.tsx         # User input
│       │   ├── MarkdownRenderer.tsx
│       │   ├── ProgressBar.tsx
│       │   ├── ReasoningDisplay.tsx    # LLM reasoning
│       │   ├── SessionStats.tsx
│       │   ├── SimpleDiff.tsx
│       │   ├── SlashCommands.tsx       # 30+ commands
│       │   ├── StatusNotification.tsx
│       │   ├── StreamingText.tsx       # Live text output
│       │   ├── TodoPlanDisplay.tsx     # Task visualization
│       │   ├── ToolCallDisplay.tsx
│       │   ├── ToolInvocationBlock.tsx
│       │   ├── ToolResultCard.tsx      # Structured results
│       │   ├── ToolResultDisplay.tsx
│       │   ├── TypewriterText.tsx
│       │   ├── UpdateNotice.tsx
│       │   ├── streamingTextFlush.ts
│       │   └── toolCallRenderers.tsx
│       ├── constants/
│       │   ├── historyLayout.ts
│       │   ├── inputPaste.ts
│       │   └── toolUiPreview.ts
│       ├── hooks/
│       │   └── useAtCompletion.ts
│       ├── theme/
│       │   ├── blumaTerminal.ts
│       │   └── m3Layout.tsx
│       └── utils/
│           ├── clipboardImage.ts
│           ├── editToolDiffUtils.ts
│           ├── expandPreviewHotkey.ts
│           ├── expandablePreviewStore.ts
│           ├── formatTurnDurationMs.ts
│           ├── inlineImageInputLabels.ts
│           ├── pathDisplay.ts
│           ├── shellToolNames.ts
│           ├── slashRegistry.ts
│           ├── terminalTitle.ts
│           ├── toolDisplayLabels.ts
│           ├── toolInvocationPairing.ts
│           └── useSimpleInputBuffer.ts
├── main.ts                             # Entry point
└── types/
    └── semver-functions.d.ts
```

---

## Testing

```bash
npm test            # Run all tests
npm run test:watch  # Watch mode
```

### Test Structure

```
tests/                    # 33 test files (flat structure)
├── 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
└── ...                   # Additional integration and unit tests
```

---

## Contributing

See [CONTRIBUTING.md](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](LICENSE) for details.

---

## Support

- **Issues**: [GitHub Issues](https://github.com/nomad-e/bluma-cli/issues)
- **Documentation**: This README + `docs/` directory
- **Author**: Alex Fonseca
- **npm Package**: [@nomad-e/bluma-cli](https://www.npmjs.com/package/@nomad-e/bluma-cli)

### Runtime Modules (v0.1.41+)

BluMa's runtime layer provides enterprise-grade orchestration:

| Module | Purpose | Key Features |
|--------|---------|--------------|
| `task_store.ts` | Task lifecycle | PLANNING → EXECUTION → VERIFICATION phases, persistence |
| `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 |
| `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 |
|-----------|---------|
| `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 |

---

<p align="center">
  <sub>Built with ❤️ by NomadEngenuity</sub>
</p>