hanzo-repl

Hanzo REPL is a Python interactive environment for testing Hanzo MCP tools and AI integration.

Hanzo REPL - Interactive MCP Testing Environment

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-mcp.md, hanzo/hanzo-aci.md, hanzo/hanzo-chat.md

Overview

Hanzo REPL is a Python interactive environment for testing Hanzo MCP tools and AI integration. Three interfaces: a Textual TUI with command palette, an IPython REPL with magic commands, and a basic prompt-toolkit REPL. All MCP tools are available as Python functions. Chat with any LLM provider via litellm, and the LLM can call MCP tools in a loop.

Why Hanzo REPL?

Direct MCP access: All MCP tools available as Python functions with tab completion
Integrated chat: Converse with AI that can invoke MCP tools autonomously
Three interfaces: Textual TUI (default), IPython with magic commands, basic CLI
Multi-provider: Any LLM via litellm (OpenAI, Anthropic, Groq, Together, Ollama, etc.)
Voice mode: Optional speech recognition + text-to-speech (SpeechRecognition, pyttsx3)
Self-editing: Edit REPL source code from within the REPL

Tech Stack

Language: Python 3.12+
Package Manager: uv (with hatchling build backend)
TUI: Textual + textual-dev
Classic REPL: IPython, prompt-toolkit, pygments
LLM: litellm (multi-provider)
MCP: hanzo-mcp (local path dependency)
Output: Rich (tables, syntax highlighting, markdown, panels)
Voice: SpeechRecognition, pyttsx3, pyaudio, sounddevice (optional)
Testing: pytest, pytest-asyncio
Linting: ruff, black, mypy

Repo: github.com/hanzoai/repl

When to use

Testing MCP tools interactively before integrating them
Rapid prototyping with AI that has tool access
Debugging MCP tool behavior in a live environment
Building and testing agentic workflows with immediate feedback

Quick reference

| Item | Value | |------|-------| | Package | hanzo-repl | | Repo | github.com/hanzoai/repl | | Version | 0.1.0 | | License | MIT | | Python | 3.12+ | | Entry points | hanzo-repl (Textual), hanzo-repl-ipython, hanzo-repl-basic |

Installation & Setup

# Clone and setup
git clone https://github.com/hanzoai/repl
cd repl
make setup # Creates venv via uv, installs deps

# Or manually
uv venv && uv pip install -e .

Requires at least one LLM API key:

export OPENAI_API_KEY=sk-...
# or ANTHROPIC_API_KEY, GROQ_API_KEY, TOGETHER_API_KEY, etc.

Usage

Start the REPL

make dev # Textual TUI (default, recommended)
make dev-ipython # IPython with magic commands
make chat # Basic prompt-toolkit REPL

Or directly:

uv run hanzo-repl # Textual TUI
uv run hanzo-repl-ipython # IPython
uv run hanzo-repl-basic # Basic CLI

Direct Tool Access

>>> read_file(file_path="/etc/hosts")
>>> write_file(file_path="test.txt", content="Hello, World!")
>>> search(query="def main", path=".")
>>> run_command(command="ls -la")

Chat with AI + MCP Tools

>>> chat("What files are in the current directory?")
# AI calls MCP tools to answer

>>> chat("Create a Python script that prints the current time")
# AI generates and writes the file via MCP

>>> chat("Find all Python files with 'test' in the name")
# AI uses search + read tools

IPython Magic Commands

%chat What is the weather today?

%%ai
Can you help me create a web scraper?
I need it to extract titles from a list of URLs.

%tools # List available MCP tools
%tool read_file {"file_path": "README.md"} # Execute specific tool
%model claude-3-opus-20240229 # Change model
%edit_self ipython_repl.py # Edit REPL source code

REPL Commands (all interfaces)

/help Show help
/tools List available MCP tools
/providers List detected LLM providers
/model Show or set current model
/context Show conversation context
/reset Reset conversation context
/clear Clear screen
/exit Exit REPL

Makefile Targets

make dev # Start Textual TUI
make dev-ipython # Start IPython REPL
make chat # Start basic chat
make test # Run pytest
make test-integration # Run integration tests (needs API keys)
make lint # Lint with ruff
make format # Format with black + ruff
make type-check # mypy
make clean # Remove build artifacts
make build # Build distribution (swaps pyproject.toml for PyPI)
make publish # Publish to PyPI

Key Files

| File | Purpose | |------|---------| | hanzo_repl/textual_repl.py | Textual TUI with status bar, command palette | | hanzo_repl/ipython_repl.py | IPython REPL with magic commands | | hanzo_repl/repl.py | Basic prompt-toolkit REPL | | hanzo_repl/cli.py | Click CLI entry point (routes to ipython or basic) | | hanzo_repl/llm_client.py | Multi-provider LLM client (litellm wrapper) | | hanzo_repl/tool_executor.py | Executes MCP tools from LLM responses | | hanzo_repl/command_palette.py | Textual command palette widget | | hanzo_repl/command_suggestions.py | Autocomplete suggestions | | hanzo_repl/voice_mode.py | Speech recognition + TTS | | hanzo_repl/backends.py | Backend manager for LLM providers | | hanzo_repl/tests.py | Built-in test suite for MCP tools | | mcp_repl.py | Minimal direct-access REPL script |

LLM Provider Detection

The REPL auto-detects available providers by checking environment variables:

| Provider | Env Vars | |----------|----------| | OpenAI | OPENAI_API_KEY | | Anthropic | ANTHROPIC_API_KEY, CLAUDE_API_KEY | | Google | GOOGLE_API_KEY, GEMINI_API_KEY | | Groq | GROQ_API_KEY | | Together | TOGETHER_API_KEY | | Ollama | (no key needed) | | Bedrock | AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY |

Related Skills

hanzo/hanzo-mcp.md - MCP server that provides the tools
hanzo/hanzo-aci.md - Agent Computer Interface (file editing, linting, shell)
hanzo/hanzo-chat.md - Chat UI (REPL can serve as MCP backend for Chat)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: repl, mcp, interactive, testing, python, textual, ipython, llm Prerequisites: Python 3.12+, uv, at least one LLM API key