Advanced Usage

Non-Interactive / CI Mode

Run Hanzo Dev headless in pipelines:

- name: Update changelog via Hanzo Dev
  run: |
    npm install -g @hanzo/dev
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    dev exec --full-auto "update CHANGELOG for next release"

Resuming Non-Interactive Sessions

# Picker
dev resume

# Most recent
dev resume --last

# Specific session
dev resume <SESSION_ID>

Tracing / Verbose Logging

Enable debug mode for detailed logging:

dev --debug "your prompt"

When --debug is enabled, request/response JSON is partitioned into helper-specific folders under ~/.hanzo/debug_logs/:

auto/coordinator
auto/observer/bootstrap
auto/observer/cadence
auto/observer/cross_check
guided_terminal/agent_install_flow
tui/rate_limit_refresh
ui/theme_spinner
cli/manual_prompt

Monitor logs in real-time:

tail -F ~/.hanzo/debug_logs/codex-tui.log

Without --debug, only critical crash/error logs are written to ~/.hanzo/debug_logs/critical.log.*.

Model Context Protocol (MCP)

Configure MCP servers in ~/.hanzo/config.toml:

[mcp_servers.server-name]
command = "npx"
args = ["-y", "mcp-server"]
env = { "API_KEY" = "value" }

Using Hanzo Dev as an MCP Server

Hanzo Dev can also run as an MCP server:

dev mcp

Test with the MCP inspector:

npx @modelcontextprotocol/inspector dev mcp

Send a tools/list request to see the available dev tool that accepts a catch-all of inputs including a config map for overrides.

MCP Management

# Add a custom MCP server
dev mcp add my-search -- /path/to/search-mcp

# Add remote server with auth
dev mcp add api-tool --url https://api.example.com --bearer-token $TOKEN

# List configured servers
dev mcp list --json

# Remove a server
dev mcp remove my-search