hanabi-cli

Una interfaz de chat de IA en terminal para cualquier modelo LLM, con contexto de archivos, MCP y soporte de implementación.

GitHub

Prueba este MCPPatrocinado

Documentación

hanabi-cli

⟡ Una interfaz de chat de IA en terminal para cualquier modelo de LLM, con contexto de archivos, soporte MCP y despliegue.

Agente local multi-habilidad con soporte de archivos, portapapeles y MCP
Limitado a la carpeta del proyecto - un agente diferente por proyecto
Aloja tu interfaz web de chat de agente (Next.js) desde la línea de comandos en segundos y lista para desplegar
Crea un clúster de múltiples agentes con estrategias predefinidas.
Consulta Archivo de Configuración de Hanabi para la lista completa de funciones.

Interfaz de línea de comandos

Chat demo

Interfaz web de chat

Web Chat UI

Tabla de contenidos

Instalación
CLI
Modelo predeterminado
Servidores MCP
Excluir archivos
Variables de entorno locales
Prompt de sistema personalizado
Anulación del archivo de configuración local
Modo de transmisión
Esquema de respuesta (Formato de salida determinista)
Servidor de interfaz web de chat (con APIs)
Avanzado - Sistema de múltiples agentes
Avanzado - Despliega tu agente
Pendientes

Instalación

$ npm install -g hanabi-cli

CLI

Obtener ayuda

$ hanabi --help

Iniciar sesión de chat de hanabi

$ hanabi

Restablecer archivo de configuración

$ hanabi reset

Hacer una sola pregunta e imprimir el resultado. (Sí, Hanabi inyecta automáticamente la fecha y zona horaria de hoy como contexto)

$ hanabi ask "how's the weather tomorrow?"
$ hanabi ask "generate a react todo app" > ./todo-app-instructions.md

Modelo predeterminado

El modelo predeterminado es el modelo activo que usará hanabi-cli. Esto debería configurarse para ti a través de la interfaz CLI. Ten en cuenta que la temperatura predeterminada es 0.5. Algunos modelos como GPT-5 requieren que la temperatura se establezca en 1. La configuración de temperatura se agrega en hanabi-cli en la versión 1.4.6.

También puedes modificar el modelo directamente. En tu <user home folder>/.hanabi.json, agrega o modifica el objeto defaultModel:

{
	"llms": [
		{
      "id": "fdd1abc5-6791-4c29-b754-4f1174692c22",
      "provider": "OpenAI",
      "apiKey": "your-api-key",
      "apiVersion": "2025-01-01-preview"
    },
	],
	"defaultModel": {
		"provider": "openai",
		"model": "gpt-4",
		"temperature": 0.7
	}
}

Servidores MCP

En tu <user home folder>/.hanabi.json, agrega la configuración mcpServers.

{
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	},
	"mcpServers": {
		"home-ai": {
			"name": "Home AI",
			"transport": "stdio",
			"command": "node",
			"args": ["c:/folder/home-mcp.js"]
		},
		"context7": {
			"name": "context7",
			"transport": "stdio",
			"command": "npx",
			"args": ["-y", "@upstash/context7-mcp@latest"]
		},
		"browser-use": {
			"name": "Browser-use automation",
			"transport": "sse",
			"url": "http://172.17.0.1:3003/sse",
			"headers": {
				"authentication": "Bearer api-token"
			}
		},
		// npx stdio approach is flaky & slow. highly recommend
		// to npm install -g <mcp-server> and use the following.
		// see https://github.com/modelcontextprotocol/servers/issues/64
        // "file-system": {
        // 	"name": "file system",
        // 	"transport": "stdio",
        // 	"command": "path/to/your/node.exe",
        // 	"args": [
		// "path/to/global/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "."]
        // },
		"tavily": {
			"name": "Tavily Search",
			"transport": "stdio",
			"command": "npx",
			"env": {
				"TAVILY_API_KEY": "your-api-key"
			},
			"args": ["-y", "tavily-mcp@0.1.4"]
		},
		// npx is slow! use above recommendation
		"file-system": {
			"name": "file system",
			"transport": "stdio",
			"command": "npx",
			"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
		},
		"my-calendar": {
			"name": "My Calendar",
			"transport": "streamable_http",
			"url": "http://172.17.0.1:3001/mcp",
			"headers": {
				"authentication": "Bearer my-auth-token"
			}
		}
	}
}

Excluir archivos

Para evitar que se acceda a archivos, agrega patrones globby en la configuración

Todos los archivos incluidos en .gitignore también se excluirán automáticamente.

// <user home folder>/.hanabi.json
{
	"exclude": ["certificates", "screenshots/**/*", "passwords/*", "*.pid"],
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Variables de entorno locales

Hanabi admite archivos de entorno locales (.env). También puedes agregar el campo envs a .hanabi.json. Usa el prefijo de URL file:// para inyectar contenido de archivo como variable de entorno. Solo admite archivos de texto plano, por ejemplo, *.json, *.txt, *.html, etc. Para inyectar contenido de archivos PDF en process.env, conviértelos a archivos de texto usando algo como pdf2json.

Agrega la variable de entorno ALLOWED_ORIGIN para agregar protección CORS para el servidor API.

// .hanabi.json
{
	"envs": {
		"FOO": "bar",
		"MY_DOC: "file://./README.md",
		"ALLOWED_ORIGIN": "http://localhost:3042"
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Si no deseas almacenar la clave API del proveedor u otros tokens en .hanabi.json, elimina los campos apiKey y guárdalos dentro del directorio de trabajo .env en su lugar. Los nombres de las claves son los siguientes. Consulta Proveedores o .env.example para los nombres de variables de entorno de las claves API.

OPENAI_API_KEY=xxx
GOOGLE_GENERATIVE_AI_API_KEY=xxx
DEEPSEEK_API_KEY=xxx
ANTHROPIC_API_KEY=xxx
GROQ_API_KEY=xxx
XAI_API_KEY=xxx

# MCP keys
TAVILY_API_KEY=xxx

Prompt de sistema personalizado

Hanabi viene con un prompt de sistema simple predefinido para mostrar documentación sobre comandos de terminal y proporcionar contexto de fecha y zona horaria. Puedes proporcionar un prompt de sistema adicional en hanabi.system.prompt.md en el directorio de trabajo. Usa el identificador /gen o hanabi gen para generar uno para ti.

Las variables se admiten mediante la sintaxis ${VAR_NAME}, se leen desde process.env. Consulta Variables de entorno locales.

ejemplo hanabi.system.prompt.md

# act as a polite chat bot collecting user feedback via conversational loop.

## context

Product name is ${PRODUCT_NAME}

## ask user the follwing questions one by one and prints a well formatted report

- What is your name
- How do you feel about our product? (classify answer as "Bad" | "OK" | "great")
- What is your company

Anulación del archivo de configuración local

Puedes copiar <user home folder>/.hanabi.json a tu directorio de trabajo (por ejemplo, a nivel de proyecto) para anular la configuración a nivel de usuario. Los LLM se combinan por nombre de proveedor. Usa el identificador /gen o hanabi gen para generar uno para ti.

Modo de transmisión

Alterna "streaming":true en <user home folder>/.hanabi.json o en el del directorio de trabajo.

Esquema de respuesta

Es bastante importante que el agente de flujo de trabajo genere una respuesta en un esquema determinista, por ejemplo, al pedirle al agente que genere el payload de una llamada API. Para lograrlo, define answerSchema que sea compatible con el esquema Zod en el archivo de configuración.

answerSchema se aplicará en
- respuestas de chat CLI cuando el identificador @schema esté activo
- modo de pregunta única CLI hanabi ask "list top 10 movies in 2023" > output.json
- chat de interfaz web con alternancia
- APIs del servidor, por ejemplo, /api/generate
Usa el identificador /gen o hanabi gen para generar uno para ti.
para más detalles:
- https://ai-sdk.dev/docs/reference/ai-sdk-core/json-schema
- https://v4.zod.dev/json-schema#metadata

// .hanabi.json
{
	"answerSchema": {
		"type": "object",
		"required": ["answer"],
		"properties": {
			"reason": {
				"type": "string",
				"description": "detailed reasoning for the final output."
			},
			"answer": {
				"type": "string",
				"description": "the final output without reasoning details. For math related question, this is the final output number."
			}
		}
	},
	"serve": {
 		...
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Servidor de interfaz web de chat

Se recomienda crear un .hanabi.json local para un servidor de chat independiente

En la CLI de Hanabi, usa /serve para iniciar el servidor web con el contexto actual (MCPs y prompt de sistema). Esto guardará la configuración serve en tu .hanabi.json.

Usa hanabi serve para iniciar el servidor de interfaz web directamente - útil para despliegues. Usa apiOnly para deshabilitar la interfaz de chat.

Consulta los detalles de la API del servidor aquí

// .hanabi.json
{
	"serve": {
 		"mcpKeys": ["home-ai"],
    	"port": 3041,
		/** name of the agent */
		name?: string;
		/** disable chat UI and only expose API endpoints */
		apiOnly?: boolean;
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Sistema de múltiples agentes

Puedes orquestar múltiples agentes (remotos) en varias estrategias o patrones

Ten en cuenta:

En el chat CLI, usa el identificador @agents para activar.
En el chat de interfaz web, el modo de múltiples agentes siempre está habilitado si se establece en .hanabi.json
- Solo la respuesta del agente trabajador final se transmitirá a la interfaz.

Actualmente hanabi admite los siguientes tipos de estrategia

enrutamiento (es decir, clasificación de consultas)

Consulta Archivo de Configuración de Hanabi para más detalles sobre esta estrategia.

Usa el identificador /gen o hanabi gen para generar uno para ti.

// .hanabi.json
{
	"multiAgents": {
		"strategy": "routing",
		/** default false - question with no classification
		* will be passed through to routing agent */
		"force": false,
		"agents": [
			{
				"name": "calendars",
				"apiUrl": "http://localhost:3051/api",
				"classification": "school calendar events and UK public holiday"
			},
			{
				"name": "math",
				"apiUrl": "http://localhost:3052/api",
				"classification": "math problem"
			},
			{
				"name": "api-doc",
				"apiUrl": "http://localhost:3053/api",
				"classification": "API document"
			}
		]
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

flujo de trabajo (es decir, ejecutar agentes trabajadores secuencialmente)

Consulta Archivo de Configuración de Hanabi para más detalles sobre esta estrategia.

en este modo, se ignora el historial de chat. Cada mensaje de usuario activa un nuevo flujo de trabajo independiente.
Usa el identificador /gen o hanabi gen para generar uno para ti.

// .hanabi.json
{
	"multiAgents": {
		"strategy": "workflow",
		"steps": [
			{
				"apiUrl": "http://localhost:3051/api",
				"name": "process user email into trade instruction"
			},
			{
				"apiUrl": "http://localhost:3052/api",
				"name": "trade booking with payload"
			}
		]
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

paralelo (es decir, multitarea)

Consulta Archivo de Configuración de Hanabi para más detalles sobre esta estrategia.

envía la consulta del usuario a múltiples agentes para diferentes tipos de tareas en paralelo y genera un resumen agregado.
Usa el identificador /gen o hanabi gen para generar uno para ti.

// .hanabi.json
{
	"multiAgents": {
		strategy: 'parallel',
		agents: [
			{
				name: 'code quality agent',
				apiUrl: 'http://localhost:3051/api',
				prompt:
					'Review code structure, readability, and adherence to best practices.',
			},
			{
				name: 'code performance agent',
				apiUrl: 'http://localhost:3052/api',
				prompt: 'Identify performance bottlenecks & memory leaks.',
			},
			{
				name: 'code security agent',
				apiUrl: 'http://localhost:3053/api',
				prompt:
					'Identify security vulnerabilities, injection risks, and authentication issues',
			},
		],
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Despliegue con Docker

Consulta la carpeta docker-agent-example para ver cómo desplegar tu agente como una imagen de Docker.

hanabi-cli

Documentación

hanabi-cli

Interfaz de línea de comandos

Interfaz web de chat

Tabla de contenidos

Instalación

CLI

Modelo predeterminado

Servidores MCP

Excluir archivos

Variables de entorno locales

Prompt de sistema personalizado

Anulación del archivo de configuración local

Modo de transmisión

Esquema de respuesta

Servidor de interfaz web de chat

Sistema de múltiples agentes

enrutamiento (es decir, clasificación de consultas)

flujo de trabajo (es decir, ejecutar agentes trabajadores secuencialmente)

paralelo (es decir, multitarea)

Despliegue con Docker

Pendientes