Hanzo REPL

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`

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)

On this page