hanabi-cli

⟡ A terminal AI chat interface for any LLM model, with file context, MCP and deployment support.

- Local multi skilled agent with files, clipboard & MCP support
- Project folder scoped - different agent per project
- Host your agent web chat UI (Next.js) from command line in seconds and ready for deployment
- Create a multi-agent cluster with predefindstrategies.
- CheckoutHanabi Config Filefor full list of features.

- Install
- CLI
- Default Model
- MCP Servers
- Exclude files
- Local envs
- Custom System Prompt
- Local config file override
- Streaming Mode
- Answer Schema (Deterministic Output Format)
- Web Chat UI Server (with APIs)
- Advanced - Multi Agents System
- Advanced - Deploy Your Agent
- TODOs

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

{ "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 } }

In your<user home folder>/.hanabi.json, addmcpServersconfig.

{ "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" } } } }

To prevent files from being accessed, addglobbypatterns in the config

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

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

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

# 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

// .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": { // ... } }

It's recommended to create a local.hanabi.jsonfor independent chat server

// .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": { // ... } }

// .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": { // ... } }

workflow (i.e. run worker agents sequentially)

seeHanabi Config Filefor more details on this strategy.

// .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": { // ... } }

seeHanabi Config Filefor more details on this strategy.

// .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": { // ... } }

Seedocker-agent-examplefolder to see how to deployment your agent as a docker image.

- include local files in chat
- mcp support
- add config to exclude custom files pattern
- support for custom system prompt (via local .md file)
- support working dir level.hanabi.jsonoverride, smililar to how .npmrc works
- streaming mode
- add web server chat bot mode (ie api and web interface)
- improve web server mode (API keys, UX improvements, Update UI mode readme)
- Multi Agent System(WIP)
- web ui file support

Tools for logging, analyzing, and improving Claude Desktop prompts to enhance prompt engineering skills.