Skip to content
Wolkyen
API

Flagship

Magi Bot

Wolkyen’s Grok-like bot engine: named bots, isolated workspaces, and a confirm step only when a bot wants to move a file out of its folder. The download is a Python module. It does not open a window — you write the UI in a separate file. formatter.py is required in the same folder.

Required. formatter.py must sit next to magi_bot.py. Magi Bot imports format_markdown_and_latex at load time. Without the formatter, the module will not import.

Required

formatter.py

Python module

Required. magi_bot.py imports format_markdown_and_latex at load time and will not import without this file in the same folder.

Status
Required
Size
24.5 KB
SHA-256
23c6992e26ae1c4f41dab8f05dbbefddee68867384031b54d156c7b1f42cbedc
Place next to
magi_bot.py
Download formatter.py

—

Rate Magi Bot

No reviews yet

Shared with everyone. No account.

What it is

Magi Bot is a multi-bot workspace and messaging subsystem. Each bot gets a name, a model, a color, a custom system prompt, and a folder named Magi(bot_name) under your home directory. Bots talk in complete messages and can also create, edit, move, delete, and run files — one action per step. They do not ask permission for work inside their own folder. They only ask when a move would take a file outside that workspace.

  • Up to five bots

    Each bot has its own prompt, model, and Magi(name) workspace. Names stay unique.

  • Ask only to leave the folder

    Create, edit, delete, and execute inside Magi(name) run without a prompt. The host dialog fires only if a move would take a file outside that workspace.

  • One action per step

    A small coordinator (Granite 4.1 3B) reads the last action and queues the next step.

  • Local Ollama models

    Models at 7B and up on localhost:11434. No Gemini, Mistral, OpenRouter, or Ollama Cloud.

  • Team swarm

    A three-bot collaborative mode with a live task board. No subscription gate.

  • Workspace tools

    Files, folders, venv, a short allowed-package install list, web search, fetch, headless inspect.

No host UI in the download

magi_bot.py is a module, not an app. There is no main window and nothing happens if you double-click the file. Magi Bot expects a host you write in a second file that imports the manager and draws chat. Inside a bot’s Magi(name) folder, writes and executes run without a prompt. Your host only needs a confirm dialog when a move would leave that folder. The Tkinter file below is a starter so you can see the wiring. It is not Magi’s UI and it is not professional.

How to make a UI

  1. 1

    Keep the engine, formatter, and window apart

    Save magi_bot.py and formatter.py in one folder. Your UI is a third file. Magi Bot will not import without the formatter. Do not paste a window into magi_bot.py.

  2. 2

    Import the manager, not the widgets

    from magi_bot import bot_manager, BotWorkspaceTools. List bots, store messages, resolve Magi(name) folders. MagiBotWidget is Magi-desktop PyQt code — skip it if you are writing your own host.

  3. 3

    Draw a roster and a thread

    Left: bots. Right: messages. Input at the bottom. That is the whole shape. Style is yours.

  4. 4

    Confirm only outbound moves

    If a move destination sits outside Magi(name), show the path and wait for OK. In-workspace work does not need a dialog. If the user cancels, skip the move.

  5. 5

    Drive the model from the host

    The starter does not call a model. A real host sends the user text through MagiBotWorker (PyQt) or your own loop, then applies at most one action.

Tkinter starter

A get-you-started host. Default Tk widgets, no styling, no model loop. Replace it. Do not ship it.

Download starter

—

from magi_bot import BotWorkspaceTools, bot_manager

# Separate file. This is not magi_bot.py.
bots = bot_manager.get_all_bots()
bot = bots[0]

bot_manager.add_message(bot["id"], "user", "Write notes.txt")

# In-workspace writes need no dialog.
ok, msg = BotWorkspaceTools.create_file(
    bot["workspace_dir"], "notes.txt", "hello\n"
)
# Confirm only if a move would leave Magi(name).

Magi Bot vs Hermes Agent Bot Mode

Hermes Agent v0.21.0 (31 Aug 2026, the Pantheon release) made Bot Mode a default-on roster inside Hermes Desktop: named faces, group chats, and hermes peer DMs. Magi Bot is a smaller, host-your-own engine with gated workspace tools. They solve related jobs. They are not the same product.

What it is

A Python bot engine you host. Chat plus workspace tools. Asks only to move a file out of Magi(name).

A built-in Desktop roster. Each Bot is a Hermes profile with a face and a pinned Bot Chat.

UI

Not included. You write a separate host. Tkinter starter is a sketch.

Bundled in Hermes Desktop, default-on since v0.21.0 (first shipped in v0.20.3).

Identity

Name, color, custom prompt, isolated Magi(name) folder under ~/Magi_Bots.

Name, deterministic avatar, role, skills, memory — stored as ~/.hermes/profiles/<name>/.

Talking to other bots

Solo bots, or a 3-bot swarm with a coordinator and a task board. No paywall.

Discord-style group chats, @mentions, and hermes peer DMs across profiles and gateways.

Actions

Workspace files and exec. Confirm only when a move leaves the Magi(name) folder. One action per step.

Full Hermes tool surface: skills, MCP, browser, cron, live subagent steering.

Models

Local Ollama ≥ 7B. No cloud providers.

Any model the Hermes provider list accepts.

Where it runs

Your Python process, behind a UI you own.

Hermes Desktop and CLI. Bot Mode is a UI over profiles, not a new agent runtime.

Hermes facts from the v0.21.0 changelog (Bot Mode built into the desktop; a Bot is a Hermes profile; group chats and hermes peer DMs). Magi facts from magi_bot.py.

Requirements

  • Three files in one folder: magi_bot.py, formatter.py, and a host UI you write (or the starter).
  • pip: PyQt6 and requests. No other Magi modules.
  • For inference: Ollama on localhost:11434 with a model at 7B or larger. No cloud keys, credits, or subscriptions.
  • Workspaces live in Magi_Bots in your home folder, one Magi(name) directory per bot.