agent-zero-model-switch

Instant Claude model switching for Agent Zero — just like Claude CLI.

Overview

This Agent Zero extension adds instant /model command support — switch between Claude models without restarting the container, just like the Claude CLI experience.

/model sonnet   # ⚖️ Switch to Claude Sonnet 4.6 instantly
/model haiku    # ⚡ Switch to Claude Haiku 4.5 instantly
/model opus     # 🏆 Switch to Claude Opus 4.6 instantly

No restart. No configuration files. No delay.

Prerequisites

⚠️ Important: Agent Zero runs inside a Docker container. All installation steps must be performed inside the container, not on your host machine.

You need:

• A running Agent Zero Docker container
• Access to the container terminal (via Agent Zero's built-in terminal or docker exec)
• Claude API access configured in Agent Zero settings

Supported Models

Command	Model	ID	Best For
/model haiku	⚡ Haiku 4.5	claude-haiku-4-5-20251001	Fast tasks, high volume
/model sonnet	⚖️ Sonnet 4.6	claude-sonnet-4-6	Most tasks, best value
/model opus	🏆 Opus 4.6	claude-opus-4-6	Complex reasoning, max capability

Installation

All commands must be run inside the Agent Zero Docker container.

Step 1: Access the Container Terminal

Option A: Via Agent Zero's built-in terminal Open a terminal session directly in the Agent Zero web UI.

Option B: Via Docker exec (from your host machine)

docker exec -it <your-agent-zero-container-name> bash

To find your container name:

docker ps | grep agent-zero

Step 2: Run the Installer (inside the container)

curl -sSL https://raw.githubusercontent.com/jcviau81/agent-zero-model-switch/main/scripts/install.sh | bash

The installer will:

1. Copy the extension to /a0/python/extensions/message_loop_start/
2. Patch /a0/python/helpers/extension.py to enable hot-reloading
3. Print confirmation and usage instructions

Step 3: Restart Agent Zero

Restart the container once to load the extension:

docker restart <your-agent-zero-container-name>

Or restart from Docker Desktop.

Step 4: Use /model Commands

In the Agent Zero chat, type:

/model haiku     # Switch to Haiku 4.5 (ultra-fast)
/model sonnet    # Switch to Sonnet 4.6 (balanced)
/model opus      # Switch to Opus 4.6 (maximum capability)

The switch happens instantly — no further restarts needed! ✅

---

Manual Installation

If you prefer to install manually (inside the container):

1. Copy the extension file

cp extension/_20_live_model_switch.py /a0/python/extensions/message_loop_start/

2. Patch the extension cache (enables hot-reload)

Edit /a0/python/helpers/extension.py and change line ~58 from:

if folder in _cache:

To:

if False and folder in _cache:  # disabled for hot-reload

Or apply the patch:

patch -p1 -d /a0 < patch/disable_extension_cache.patch

3. Restart Agent Zero once

---

How It Works

This extension hooks into Agent Zero's message_loop_start lifecycle event, which fires before the LLM is called on every message.

User types: /model sonnet
      ↓
message_loop_start hook fires  ← Our extension runs HERE
      ↓
Extension reads loop_data.user_message
      ↓
Detects /model command via regex
      ↓
Calls settings.set_settings_delta()  ← Updates ALL running contexts in memory
      ↓
Agent responds using the NEW model instantly! ✅

Why It Works Without Restart

Agent Zero's get_chat_model() method reads self.config.chat_model.name fresh on every API call — models are not cached. So changing the config in memory instantly affects the next response.

The settings.set_settings_delta() function calls _apply_settings() which iterates through all running AgentContext instances and updates their config.

Files

agent-zero-model-switch/
├── extension/
│   └── _20_live_model_switch.py    # Copy to: /a0/python/extensions/message_loop_start/
├── patch/
│   └── disable_extension_cache.patch  # Apply to: /a0 (inside container)
├── scripts/
│   └── install.sh                  # Run inside the container
├── LICENSE
└── README.md

Contributing

PRs welcome! Some ideas:

• Add /model status and /model list commands
• Support for other LLM providers (GPT-4, Gemini, etc.)
• Model aliases (e.g., /model fast → haiku)
• Support for newer Claude model versions

License

MIT — see LICENSE

---

Built for Agent Zero — a powerful autonomous AI agent framework.