Hablas CLI

Single-agent terminal engineering runtime — v2.5.8

One agent. Full tool access. Plans, codes, tests, commits — without switching tools or losing context. Now MCP-native.

Product principles

1. Single visible agent — no hidden routing, no multi-agent theatre
2. Fast direct path for trivial turns — instant response, no tool overhead
3. Full tool execution for real engineering work
4. Read before edit, verify before claim
5. TDD built-in — failing tests first, implementation second
6. Checkpoints — named snapshots before any risky change
7. Cross-turn reasoning memory — Hablas never forgets what it learned
8. MCP-native — act as both MCP server and client
9. Direct technical tone — no emojis, no hype, no filler

Installation

npm install -g hablas-ai

Requires Node.js 20+. One LLM provider:

| Option | Description | |---|---| | Hablas Integrated Engine | Preconfigured NVIDIA NIM backend — ready in one click on first run | | Ollama | Fully local, private, no API key | | OpenAI-compatible | Any REST endpoint |

Quick start

hablas --setup   # first-time configuration wizard
hablas           # start the agent

CLI flags

| Flag | Description | |---|---| | hablas | Start interactive session | | hablas --setup | Run the setup wizard | | hablas run <prompt> | Run a single prompt and exit | | hablas --auto | Auto mode — skip tool confirmations where allowed | | hablas --model <name> | Override the configured model | | hablas mcp-serve | Expose Hablas' tools as an MCP server over stdio | | hablas mcp | Show MCP config path and server status | | hablas --verbose | Enable verbose logging | | hablas --no-color | Disable ANSI output | | hablas --version | Print version and exit | | hablas --help | Show all flags |

MCP integration

Hablas is both an MCP server and MCP client:

As a server — hablas mcp-serve

Expose all 42 Hablas tools to any MCP-compatible host (Claude Desktop, Cursor, VS Code):

// Claude Desktop config
{
  "mcpServers": {
    "hablas": {
      "command": "hablas",
      "args": ["mcp-serve", "-p", "/your/project"]
    }
  }
}

As a client — consume external MCP servers

Connect to external MCP servers (GitHub, Playwright, databases, anything) by adding them to ~/.hablas/mcp.json (same format as Claude Desktop/Cursor):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    }
  }
}

External tools are bridged into the agent loop as first-class native tools (mcp__github__create_issue, etc.), with safety gating based on trust level.

Manage live connections with the /mcp slash command:

/mcp                    — list connected servers
/mcp trust <name>       — trust a server (confirm-level access)
/mcp reload             — reconnect after editing config
/mcp remove <name>      — remove a server

See docs/MCP.md for the complete guide.

In-session commands

Planning & execution

| Command | Description | |---|---| | /files <query> | Rank and preview the most relevant files for a task | | /git [status\|log] | Show git status, staged changes, recent commits | | /diff [file] | Show git diff |

Checkpoints

| Command | Description | |---|---| | /checkpoint save <name> | Save a named workspace snapshot | | /checkpoint list | List all saved checkpoints | | /checkpoint diff <name> | Show what changed since a checkpoint | | /checkpoint restore <name> | Restore workspace to a checkpoint |

Testing & TDD

| Command | Description | |---|---| | /tests | Run project test suite, show parsed results | | /tdd <description> | Scaffold failing tests first, then implement |

Context & memory

| Command | Description | |---|---| | /memory | Show project memory + cross-turn reasoning accumulator | | /workspace | Inspect project structure | | /help | List all available commands |

MCP

| Command | Description | |---|---| | /mcp | List connected MCP servers, tool count, trust status | | /mcp trust <name> | Trust a server (tools get confirm-level safety) | | /mcp untrust <name> | Untrust a server (tools get dangerous-level safety) | | /mcp remove <name> | Remove a server from config | | /mcp reload | Reconnect all servers after config changes |

Example workflows

TDD — write tests first, then implement

> /tdd add rate limiting to the /api/auth routes
Scaffolding tests: tests/auth-rate-limit.test.ts
  ✗ should block after 5 failed attempts  (RED)
  ✗ should reset counter after 15 minutes (RED)
Implementing: src/middleware/rate-limit.ts
Running: npx jest tests/auth-rate-limit.test.ts
  ✓ should block after 5 failed attempts  (GREEN)
  ✓ should reset counter after 15 minutes (GREEN)
Done. 2 tests passing.

Checkpoint before a risky migration

> /checkpoint save before-db-migration
Snapshot saved: before-db-migration (47 files)

> migrate the users table to UUID primary keys

> /checkpoint diff before-db-migration
Modified: prisma/schema.prisma (+12 / -3)
Added:    prisma/migrations/20260615_uuid.sql

MCP — use GitHub tools inside Hablas

> /mcp trust github
> /mcp reload
> create an issue in my repo titled "fix login bug" with body "the login form crashes on Safari"
✓ Called mcp__github__create_issue — created issue #42

Architecture

User input
  → Task analyzer (kind · complexity · language)
  → Fast path (trivial turns — no tools)
  → Full path: plan → tool execution → verification
    ├─ file-ops      (read, write, atomic patch, rollback)
    ├─ shell          (unrestricted terminal)
    ├─ git-ops        (status, diff, log, commit, stash)
    ├─ checkpoint     (save, list, diff, restore)
    ├─ run_tests      (Jest, Vitest, Pytest, Go test)
    ├─ tdd-engine     (scaffold failing tests → implement)
    ├─ codebase-graph (analyze_project, find_references, impact_analysis)
    ├─ web            (search, scrape, extract_links, read_pdf)
    ├─ image-intel    (search candidates, inspect, download)
    ├─ mcp tools      (mcp__<server>__<tool> — external MCP servers)
    └─ suggest_relevant_files (5-signal ranking)
  → LongContextAccumulator (cross-turn reasoning memory)
  → SmartContext (auto-inject top-K files for complex tasks)
  → Response

See docs/ARCHITECTURE.md for full detail.

What's new

v2.5.8 — MCP Hardening + Documentation

• MCP client: process cleanup on failure, separate timeouts, reconnect safety
• MCP bridge: tool name sanitization against injection
• MCP server: graceful shutdown (SIGINT/SIGTERM), tool call timeout (60s)
• New: docs/MCP.md — comprehensive MCP integration guide
• Updated: ARCHITECTURE.md, CLI.md, README.md with MCP sections

v2.5.7 — MCP Server + Client Integration

• hablas mcp-serve — expose all 42 tools as an MCP server over stdio
• MCP client — connect to external servers via ~/.hablas/mcp.json
• /mcp slash command — list, trust, untrust, remove, reload
• @modelcontextprotocol/sdk + zod dependencies added
• Fixed 2 pre-existing type errors (turn.ts, image-intelligence.ts)

v2.4.0 — Professional Intelligence

• Checkpoints, TDD engine, smart file discovery, reasoning memory
• 42 tools total

See CHANGELOG.md for the full history.

License

MIT — see LICENSE