MacBrain 0.4

Agente de IA local para macOS. Usa un modelo servido por LM Studio y combina conversación, memoria semántica, sesiones persistentes y herramientas con permisos verificables.

Qué puede hacer

• Conversar con modelos locales mediante LM Studio.
• Usar tool calling nativo y volver automáticamente al protocolo JSON cuando el modelo no lo soporte.
• Mantener sesiones y reanudarlas después de reiniciar el programa.
• Compactar conversaciones largas conservando objetivos y decisiones.
• Guardar memoria semántica distinguiendo usuario, agente, proyecto y entorno.
• Planificar tareas complejas y mostrar el progreso.
• Leer archivos por líneas, buscar código y analizar proyectos completos.
• Mostrar un diff, editar fragmentos exactos, ejecutar pruebas y deshacer.
• Indexar proyectos grandes para realizar búsquedas locales rápidas.
• Crear archivos de texto dentro de las carpetas permitidas y mover archivos o carpetas a la Papelera con confirmación.
• Analizar carpetas y subcarpetas, tamaños y almacenamiento.
• Abrir/cerrar apps, Finder, URLs, notificaciones, volumen y estado del sistema.
• Activar cámara y detección facial en un proceso aislado.
• Recibir peticiones por voz y responder usando la voz de macOS.
• Cargar instrucciones MACBRAIN.md por proyecto y skills locales.
• Cancelar inferencias, búsquedas, comandos o cámara con Esc.

MacBrain no usa shell=True. Los comandos de desarrollo se ejecutan como una lista de argumentos, dentro de una raíz permitida y bajo una política visible.

Instalación

1. Abre LM Studio, carga un modelo con buen soporte para herramientas e inicia el servidor local desde Developer.
2. Prepara MacBrain:

cd /TURUTA
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

3. Ejecuta:

python -m macbrain

También puedes instalar el comando del proyecto:

pip install -e .
macbrain

Interfaz

La entrada usa Prompt Toolkit para ofrecer historial persistente, sugerencias, autocompletado con Tab y una barra inferior con modelo, tokens, perfil, permisos, carpeta y sesión. Las respuestas se renderizan como Markdown y los procesos muestran estado y duración sin llenar la pantalla de paneles.

Comandos principales:

/ayuda                   Guía completa
/estado                  Estado del agente y acción pendiente
/doctor                  Diagnóstico del proveedor y dependencias
/contexto                Tokens estimados, resumen e historial
/compactar               Resume historial antiguo
/sesiones                Lista sesiones persistentes
/sesiones ID             Cambia a una sesión por ID o prefijo
/titulo TEXTO            Renombra la sesión actual
/nuevo                   Crea una sesión
/reanudar ID             Reanuda una sesión
/cd                      Abre Finder para elegir carpeta de trabajo
/cd RUTA                 Cambia la carpeta de trabajo escribiendo una ruta
/plan                    Muestra el plan activo
/deshacer                Restaura el último cambio de archivo
/memoria                 Muestra recuerdos semánticos
/herramientas            Lista herramientas
/skills                  Lista skills locales
/perfil auto|assistant|coding
/permisos                Muestra políticas efectivas
/config                  Editor interactivo con aplicación en vivo
/modelos                 Modelos del proveedor activo
/modelo use NOMBRE       Usa un modelo concreto
/modelo auto             Vuelve a selección automática
/proveedor               Lista proveedores disponibles
/proveedor use NOMBRE    Cambia entre lmstudio/gemini/openai/openrouter/ollama
/voz on|off              Respuestas habladas
/escuchar                Una petición por micrófono
/escuchar continuo       Modo Jarvis continuo
/changelogs              Cambios del proyecto
/limpiar                 Limpia la consola
/salir                   Cierra MacBrain

Agente de programación

Con el perfil auto o coding, MacBrain dispone de estas capacidades:

• inspect_project: detecta lenguajes, manifiestos y pruebas probables.
• read_text_file: lee rangos concretos con números de línea.
• search_text: busca texto o expresiones regulares recursivamente.
• index_workspace y search_workspace_index: índice SQLite local.
• preview_text_edits: produce un diff sin modificar nada.
• apply_text_edits: aplica reemplazos exactos y crea un checkpoint.
• run_workspace_command: ejecuta herramientas aprobadas sin shell.
• undo_last_file_change: restaura el último checkpoint de la sesión.

Antes de editar, el prompt del agente le exige inspeccionar, mostrar un diff y solicitar permiso. Después debe ejecutar una prueba o verificación relevante.

Puedes añadir instrucciones al proyecto creando MACBRAIN.md en una carpeta permitida. Las instrucciones más cercanas a la carpeta de trabajo complementan las de sus carpetas superiores, sin poder reemplazar las reglas de seguridad.

Permisos

El runtime, no el modelo, decide si una herramienta puede ejecutarse. Aunque el modelo intente enviar confirm=true, ese valor se elimina. Una confirmación se vincula a una herramienta y argumentos exactos, expira y solo acepta una respuesta afirmativa posterior del usuario.

Modos generales:

• safe: pregunta antes de escribir y ejecutar.
• advanced: marca todas las herramientas registradas como allow.
• assistant: perfil sin herramientas de programación.
• coding: perfil con herramientas de proyecto.
• auto: deja todas las capacidades disponibles para que el modelo elija.

Reglas por herramienta:

/permisos allow apply_text_edits
/permisos ask move_to_trash
/permisos ask open_application
/permisos deny run_workspace_command
/permisos default apply_text_edits

Las reglas se guardan en .macbrain/permissions.json.

Cambiar con /config set MACBRAIN_PERMISSION_MODE=advanced escribe allow para todas las herramientas actuales. Volver a /config set MACBRAIN_PERMISSION_MODE=safe limpia esos overrides y restaura la política segura por defecto.

/cd sin ruta, /cd ruta o /cd seleccionar abren un selector nativo de macOS. La carpeta elegida debe estar dentro de las raíces permitidas; si no, agrégala con /config add-root RUTA.

Sesiones, contexto y memoria

Las sesiones, planes, checkpoints e índice se guardan en .macbrain/state.db. El historial del prompt está en .macbrain/prompt_history y los eventos técnicos, sin contenido de mensajes ni argumentos, en .macbrain/events.jsonl.

Al atender la primera petición, MacBrain consulta la ventana con la que LM Studio cargó el modelo y usa el menor valor entre esa cifra y la configuración local. El presupuesto también reserva los tokens de los esquemas de herramientas y de la respuesta.

Cuando el contexto se acerca al límite, MacBrain crea un resumen acumulativo por bloques y conserva los últimos turnos completos. SQLite registra hasta qué mensaje cubre ese resumen, de modo que al reiniciar sólo se cargan los turnos posteriores. Si LM Studio rechaza una petición por exceso de contexto, el agente aprende el límite reportado, compacta y reintenta automáticamente. No existen tokens infinitos, pero este ciclo permite mantener sesiones de varias horas sin reenviar toda la conversación en cada turno.

La memoria sigue en .macbrain_memory.json para facilitar su inspección y migración. Cada recuerdo incluye sujeto, atributo, valor y confianza. human_user designa exclusivamente a la persona y macbrain_agent al asistente. El modelo decide semánticamente si una frase habla de uno u otro mediante la herramienta remember_fact; el runtime de producción no depende de una frase exacta como "tu nombre es".

Voz

La salida usa say de macOS. La entrada usa SpeechRecognition para capturar el micrófono y whisper.cpp para transcribir localmente. En macOS:

brew install portaudio whisper-cpp
pip install PyAudio
hf download ggerganov/whisper.cpp ggml-base.bin --local-dir .macbrain/models

El modelo predeterminado queda en .macbrain/models/ggml-base.bin; puede cambiarse con MACBRAIN_WHISPER_MODEL. El modo auto prioriza whisper.cpp, después intenta otros transcriptores locales disponibles.

La transcripción online está desactivada por defecto. Puede habilitarse desde /config con MACBRAIN_ALLOW_ONLINE_SPEECH=true.

Cámara

La cámara siempre requiere permiso salvo una regla explícita del usuario. Por defecto OpenCV se ejecuta en otro proceso; si la biblioteca nativa falla, el CLI continúa vivo y el proceso de cámara se termina. q, cerrar la ventana, Esc o el timeout liberan la cámara y destruyen las ventanas de OpenCV.

Configuración

Consulta .env.example para todos los valores. Los más importantes son:

MACBRAIN_PROVIDER=lmstudio
LM_STUDIO_MODEL=
LM_STUDIO_FAST_MODEL=
GEMINI_API_KEY=
GEMINI_MODEL=
OPENAI_API_KEY=
OPENAI_MODEL=
OPENROUTER_API_KEY=
OPENROUTER_MODEL=
OLLAMA_MODEL=
MACBRAIN_AGENT_PROFILE=auto
MACBRAIN_TOOL_PROTOCOL=auto
MACBRAIN_PERMISSION_MODE=safe
MACBRAIN_CONFIRM_WRITES=true
MACBRAIN_MAX_CONTEXT_TOKENS=16000
MACBRAIN_CONTEXT_RESERVE_TOKENS=2048
MACBRAIN_AUTO_COMPACT=true
MACBRAIN_STATE_DIR=.macbrain
MACBRAIN_WHISPER_MODEL=.macbrain/models/ggml-base.bin
MACBRAIN_ISOLATE_VISION=true

/config guarda y aplica los cambios sin reiniciar. Las raíces permitidas se validan después de expandir y resolver la ruta.

Proveedores:

/proveedor use lmstudio
/proveedor use gemini
/proveedor use openai
/proveedor use openrouter
/proveedor use ollama
/modelo use qwen-3-14b-instruct
/modelo auto

Gemini, OpenAI y OpenRouter necesitan su API key en .env o con /config set CLAVE=valor. Ollama queda preparado para cuando instales su servidor local.

/modelos detecta catálogos por proveedor: Gemini usa su endpoint v1beta/models, OpenRouter usa /api/v1/models, Ollama usa /api/tags y los demás proveedores usan el endpoint OpenAI-compatible /models. En Gemini, MacBrain oculta modelos que Google aún enumera pero rechaza para usuarios nuevos, y si un modelo configurado queda obsoleto intenta cambiar una vez a un alias actual como gemini-flash-latest.

Skills

Una skill local vive en:

.macbrain/skills/NOMBRE/SKILL.md

El agente puede descubrirla con list_skills y debe leerla completa con read_skill antes de usarla. Esto permite añadir flujos especializados sin agrandar el prompt principal.

Desarrollo y pruebas

.venv/bin/python -m py_compile macbrain/*.py macbrain/tools/*.py tests/*.py
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m ruff check macbrain tests

La arquitectura detallada está en ARCHITECTURE.md.