◆ Hablas CLI

Premium multi-agent AI coding agent for your terminal

Local-first · Cloud-compatible · Watch the team work in front of you

by Abdulmoin Hablas

✦ Overview

Hablas is a multi-agent AI development system that runs in your terminal. Unlike single-model assistants, Hablas leads a team of specialists — Emma (Product), Bob (Architect), Alex (Engineer), David (Analyst) — and you watch them collaborate live, in character, while Hablas (the Team Leader) remains your single point of contact.

It runs locally via Ollama, or against any OpenAI-compatible API (NVIDIA NIM, OpenAI, Groq, Together, OpenRouter, and more).

✨ What makes v1.0.0 different

• Live Team Theatre — see the team handoff tasks, think, run tools, and review each other's work in real time, with an executive-silver TUI.
• Hablas-only conversation — you talk to one leader; the rest is theatre.
• Persona-faithful — each agent stays in their distinctive voice (Hablas is INTJ-direct, Bob is methodical, Alex is pragmatic, …).
• Token-bounded dialogue — the inter-agent chat is capped and gracefully falls back to deterministic lines when offline.

Key Features

• Multi-Agent System — 5 specialized agents with their own mindsets and (optionally) their own models per role.
• T-shirt Sizing — XS/S/M/L/XL routing so a "hi" doesn't trigger a plan.
• Plan Approval — for L/XL tasks, you approve / edit / skip before exec.
• Dual Provider — Ollama (local), NVIDIA NIM, or any OpenAI-compatible API. Switch live with /provider.
• Dynamic Model Discovery — /models lists everything your API exposes.
• Agentic Loop — multi-step tool execution with auto-retry, smart abort, and recovery hints.
• 15+ Built-in Tools — file ops, shell, codebase search, web search, web scraping, PDF reading, code execution, bug detection, and more.
• Smart Context — project-aware prompts, memory with categories and importance decay, shared notebook, auto-injection of mentioned files.
• Premium TUI — executive-silver theme, spinners, progress, plan boxes, session summaries.
• Three-tier safety — safe / confirm / dangerous per tool.
• Ctrl+C UX — single = cancel current op, double = exit cleanly.
• Auto Mode — --auto skips tool confirmations for scripting (plan approval still required).
• Checkpoints & Undo — /checkpoint save|restore, /undo.
• Team Mode — optional Supabase + Git-based locks and presence sync.

✦ Installation

git clone https://github.com/Monopoly63/mobile-bot.git
cd mobile-bot/flowagent
npm install
npm run build
npm link        # exposes the `hablas` command globally

Requirements

• Node.js 20+
• One of:
  • Ollama running locally (ollama serve)
  • An OpenAI-compatible API key
  • NVIDIA NIM API key

First run launches a setup wizard. You can re-run it anytime with hablas --setup.

✦ Quick Start

# Interactive REPL
hablas

# One-shot command
hablas run "refactor src/auth.ts to use bcrypt"

# Generate a commit message from staged changes
hablas commit

# Project info
hablas info

# Diagnostics
hablas doctor

✦ Commands Reference

Core Slash Commands

| Command | Description | |---|---| | /help | List all commands | | /about · /version | Identity & version info | | /team · /agents | Team roster · multi-agent system status | | /agents on\|off\|status\|models | Toggle and inspect agents | | /delegate <agent> <task> | Manually assign a task to one agent | | /mindset <name> · /mindsets | Switch / list agent mindsets | | /clear · /history [n] | Reset context · show recent turns | | /status · /quit | Show status · exit |

Model & Provider

| Command | Description | |---|---| | /model [name] | Show or switch the active model | | /models [page\|query] | Browse available models (paged + search) | | /provider [ollama\|nvidia\|custom\|test] | Switch / test the provider | | /addmodel · /listmodels · /usemodel <name> · /removemodel <name> | Manage saved provider profiles |

Project Tools

| Command | Description | |---|---| | /security | Run the project security scan | | /git status | Show Git status | | /workspace | Show framework/language/CI detection | | /stats · /cost | Usage analytics | | /test [--fix] | Detect & run tests, optionally let the agent fix them | | /checkpoint save\|list\|restore\|delete | Snapshot & restore project state | | /undo [N\|all\|list] | Revert recent agent changes | | /compare <a> <b> · /compare HEAD~1 | Side-by-side diff |

Memory & Context

| Command | Description | |---|---| | /memory [set\|del\|search\|clear] | Persistent project memory | | /learn "<preference>" | Teach the agent a preference (importance: 9) | | /context [set\|get\|del\|decisions\|clear] | Cross-agent shared notebook | | /plan status\|finish\|next\|reset | Inspect the active plan |

Plugins & Diagnostics

| Command | Description | |---|---| | /plugins [enable\|disable] | Manage plugins (~/.hablas/plugins/) | | /alias [set\|del] | Custom command aliases | | /doctor | System diagnostics | | /session save\|list | Save/load conversation state |

✦ CLI Flags & Sub-commands

| Flag / Sub-command | Description | |---|---| | -m, --model <name> | Set the active model | | -p, --project <path> | Set the working directory | | --provider <ollama\|custom\|nvidia> | Choose LLM provider | | --api-url <url> · --api-key <key> | Configure custom/NVIDIA provider | | --auto | Skip tool confirmations (plan approval still required) | | --timeout <ms> | Per-request timeout (default 120000) | | --theme <dark\|light\|galaxy\|ocean\|forest> | UI theme | | --team --user <name> --team-key <pwd> | Enable Team Mode | | --setup | Run the first-time wizard | | hablas run "<prompt>" | Non-interactive single shot | | hablas commit · pr · changelog | Git intelligence sub-commands | | hablas info · doctor · security · stats | Project insights | | hablas api --port 8080 | Start the REST API server |

✦ Built-in Tools

| Tool | Purpose | Safety | |---|---|---| | read_file, list_dir, get_file_info | Read filesystem | safe | | write_file, edit_file, patch_file, append_to_file, search_and_replace | Mutate files | confirm | | delete_file, move_file, create_dir | Manage paths | dangerous / confirm | | run_command | Shell execution (with timeout + blocklist) | dangerous | | search_codebase | Ripgrep-style search | safe | | detect_bugs | Static analysis | safe | | web_search | DuckDuckGo search | safe | | scrape_url, extract_links | HTML scraping | safe | | read_pdf, pdf_metadata | PDF reading | safe | | execute_code | Sandboxed code execution | confirm |

✦ Configuration

Config lives at ~/.hablas/config.json. Sub-files:

| File | Purpose | |---|---| | ~/.hablas/config.json | Main config (model, provider, theme, flags) | | ~/.hablas/agent-models.json | Per-agent model overrides | | ~/.hablas/models.json | Saved provider profiles (/addmodel) | | ~/.hablas/aliases.json | Custom slash-command aliases | | ~/.hablas/memory/<hash>.json | Per-project memory store | | ~/.hablas/plugins/ | Installed plugins | | ~/.hablas/logs/ | Structured pino logs |

✦ The Multi-Agent Team

| Agent | Title | Role | Voice | |---|---|---|---| | ★ Hablas | Team Leader | Coordination, planning, synthesis, the only one you talk to | INTJ, authoritative, terse | | ◆ Emma | Product Manager | Requirements, PRDs, user stories | Calm, structured | | ◆ Bob | Architect | System design, schemas, contracts, peer-reviews Alex | Methodical, principled | | ◆ Alex | Engineer | Implementation, debugging, tests | Pragmatic, action-biased | | ◆ David | Data Analyst | Research, documentation, comparisons | Factual, evidence-driven |

Routing is automatic and complexity-aware (T-shirt sizing):

| Size | Trigger | Behavior | |---|---|---| | XS | Greetings, casual chat | Hablas replies directly, no tools | | S | Single clear question | Single agent, no plan | | M | Single focused task | Live theatre, one specialist + Hablas synthesis | | L | Multi-step, multi-concern | Plan → approval → live theatre with peer review | | XL | Full system / feature | XL plan (Emma writes PRD first) → approval → full theatre |

✦ Examples

# Read, then edit
> read src/auth.ts and add JWT validation

# Multi-step (triggers L flow)
> design and implement a /users endpoint with tests

# Specific agent
> /delegate bob design the cache layer for the search API

# Git workflow
> hablas commit
> hablas pr --base main
> hablas changelog --version 1.1.0

# Memory
> /learn always use tabs and 2-space indent for YAML
> /memory search auth

✦ Architecture

src/
├── repl/          REPL loop, slash commands, TUI, live theatre
├── agents/        Orchestrator, conductor, runner, channel, dialogue
├── planner/       T-shirt sizing, plan lifecycle, task queue
├── llm/           Unified provider (Ollama/Custom/NVIDIA), tool parser v2
├── mindset/       Per-agent system prompts
├── tools/         Tool registry + 15 built-in tools
├── context/       Session, memory, shared notebook, auto-inject
├── config/        Defaults + JSON loader
├── collaboration/ Optional Team Mode (Supabase + Git locks)
├── plugins/       Plugin loader + diagnostics
├── security/      /security scanner
├── analytics/     Usage stats
├── git/           /commit /pr /changelog intelligence
├── workspace/     Framework / language / CI detection
└── utils/         logger, diff, tokens

74 TypeScript files, ~21,000 LOC, strict mode, zero @ts-ignore, zero unused locals/parameters.

✦ Development

npm install        # install deps
npm run build      # tsc → dist/
npm run lint       # tsc --noEmit
npm test           # run the channel unit tests
npm run dev -- run "your prompt"  # dev mode without build

✦ Author

Abdulmoin Hablas — Portfolio

Other Projects

• mobile-bot — the web companion + landing pages
• Hablas Web Chat — ChatGPT-style chat on the web

✦ License

MIT © 2024-2026 Abdulmoin Hablas