@nomad-e/bluma-cli

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