BluMa CLI

BluMa é o agente de linha de comando da Nomad-e para engenharia de software: interface terminal, ferramentas nativas, sessões persistentes, memória em disco e integração com o Factor Router para modelos. Em modo sandbox, o BluMa cria e faz deploy de apps FactorAI.sh dentro de um workspace isolado.

Início rápido

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

export FACTOR_ROUTER_URL=https://seu-factor-router/v1
export FACTOR_ROUTER_KEY=sua-chave

bluma                    # nova sessão
bluma resume             # retomar (menu)
bluma resume <session_id>

Desenvolvimento local:

git clone https://github.com/Nomad-e/bluma-cli.git
cd bluma-cli
npm install
cp .env.example .env
npm run build
npm start

Funcionalidades

Interface terminal

• Chat com streaming, raciocínio do modelo e execução de ferramentas
• Histórico e retoma de sessões
• Comandos / para sessão, git, memória, sandbox, inspeção e mais
• Modos local e sandbox (permissões e workspace)

Modelos (Factor Router)

O BluMa fala com o Factor Router via API OpenAI-compatible. Configuração:

| Variável | Descrição | |----------|-----------| | FACTOR_ROUTER_URL | URL base do router (ex. https://…/v1) | | FACTOR_ROUTER_KEY | Chave de autenticação |

O router escolhe o modelo; não precisas de configurar endpoints de LLM no BluMa além destas duas variáveis.

Memória

O BluMa guarda contexto persistente em ficheiros sob ~/.bluma:

| Tipo | Onde | Para quê | |------|------|----------| | Auto-memory | projects/<projeto>/memory/ (MEMORY.md e tópicos .md) | Preferências e factos do projeto; entra no prompt; o agente atualiza com as tools de ficheiro | | Extração automática | Mesma pasta | Após cada turno, um subagente pode consolidar notas (BLUMA_DISABLE_EXTRACT_MEMORIES=1 desliga) | | Session memory | <sessionId>/session-memory/summary.md | Resumo da conversa atual | | BLUMA.md | Raiz do projeto ou ~/.bluma | Instruções e regras do projeto | | Coding memory | Ficheiro dedicado | Notas de código via tool coding_memory | | Agent memory | .bluma/agent-memory/ | Memória por perfil de agente (user / project / local) |

Flags úteis: BLUMA_DISABLE_AUTO_MEMORY, BLUMA_DISABLE_SESSION_MEMORY, BLUMA_HOME.

Sandbox e FactorAI.sh

Com sandbox ativo (BLUMA_SANDBOX), o BluMa corre no workspace isolado com tools dedicadas:

• Scaffold Next.js, deploy, edição incremental (apply_app_changes), estado e redeploy
• Deploy empacota o projeto em ZIP no próprio Node (sem depender de zip no sistema)
• Cada session_id mantém o seu workspace — uma app por sessão de chat
• Evento factor-sh-url-app com o URL da app publicada

O orchestrator (ex. sandbox-api) injeta SEVERINO_URL, FACTORAI_BASE_URL, chaves de API e BLUMA_SANDBOX_WORKSPACE.

Modo agente (headless)

Para automação ou gateway (JSON in / JSONL out):

bluma agent --input-file request.json

Eventos: log, backend_message, result (inclui URL da app quando há deploy). Scripts de teste em scripts/.

Ferramentas e skills

• Tools nativas: ficheiros, shell, planeamento, pesquisa, MCP, multi-agente, FactorAI em sandbox — ver src/app/agent/tools/
• Skills embutidas: factorai-sh, git-commit, git-pr, git-release, pdf, xlsx, skill-creator
• Skills extra: .bluma/skills/, ~/.bluma/skills/

Multi-agente

Coordenador, workers e mailbox em ~/.bluma/mailboxes/ (spawn_agent, wait_agent, send_message, …).

Integrações

• MCP — ~/.bluma/bluma-mcp.json
• VS Code — extensão em vscode-extension/
• Native — clipboard e layout (native/)

Configuração

Exemplo mínimo (.env):

FACTOR_ROUTER_URL=https://your-factor-router.example/v1
FACTOR_ROUTER_KEY=your-key

Opcionais comuns: BLUMA_PERMISSION_MODE, BLUMA_HOME, flags de memória, URLs FactorAI para testes de deploy local, MCP_SSE_URL. Ver .env.example.

Sessões

• Índice em SQLite + histórico em disco (~/.bluma)
• bluma resume — menu ou ID
• bluma sessions / bluma logs <id> — agentes em background

Desenvolvimento

| Comando | Descrição | |---------|-----------| | npm run build | Compila para dist/ | | npm run build:all | Native (Rust) + build | | npm start | Build e UI | | npm test | Testes | | npm run lint | ESLint |

Requisitos: Node.js ≥ 20.

Documentação

| Documento | Conteúdo | |-----------|----------| | CHANGELOG.md | Versões | | CONTRIBUTING.md | Como contribuir | | docs/BLUMA_DEVELOPER_GUIDE.md | Guia de desenvolvimento | | docs/SKILLS.md | Skills | | docs/FACTOR_ROUTER_TURNS.md | Turnos no router | | docs/MAILBOX_IPC.md | Mailbox |

Licença

Apache 2.0 — LICENSE

Alex Fonseca · Nomad-e