hablas-ai

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