hubzoid 0.2.3

Drop a folder of markdown files, get a chat agent with a polished web UI.

Drop a folder of markdown files. Get a chat agent with a polished web UI.

---

hubzoid reads AGENTS.md, agents/, skills/, and knowledge/ from a folder and turns it into a running AI agent. Backed by the OpenAI Agents SDK or the Claude Agent SDK, served over an OpenAI-compatible HTTP API, and chattable through a bundled Open WebUI front end.

You write the markdown. hubzoid handles the runtime, the API, the UI, the streaming, and the sub-agent routing. Provider-agnostic via LiteLLM: OpenRouter, OpenAI, Anthropic, and local Claude work out of the box.

Quickstart

3 steps if you have claude CLI installed and logged in, 4 otherwise.

pip install hubzoid
hubzoid init demo-hub                  # scaffolds a starter hub + agents-repo wrapper
*  edit demo-hub/.env                  # ← optional. skip if using claude-local.
hubzoid run demo-hub

Open http://localhost:3080. The scaffolded demo-hub is a working Hubzoid Guide agent.

* Step 3 (the optional one). Default MODEL=claude-local uses your installed claude CLI subscription. If you already ran claude login, skip this step and go straight to hubzoid run. Otherwise, open demo-hub/.env, comment out the MODEL=claude-local line, and uncomment one of the provider stanzas (OpenRouter, OpenAI, Anthropic) with your key pasted in.

The two files you edit later as you customize:

1. demo-hub/.env: keys, model selection, UI knobs.
2. demo-hub/AGENTS.md: the system prompt body. YAML frontmatter sets name, description, and optional model.

How it works

┌─────────────────────────────┐
│  Open WebUI                 │  http://localhost:3080
│  (web chat, white-label)    │
└──────────────┬──────────────┘
               │ OpenAI-compatible HTTP
┌──────────────┴──────────────┐
│  FastAPI bridge             │  /v1/chat/completions  /v1/models
└──────────────┬──────────────┘
               │ in-process
┌──────────────┴──────────────┐
│  Agent runtime              │  OpenAI Agents SDK  |  Claude Agent SDK
└──────────────┬──────────────┘
               │ LiteLLM (or claude CLI subprocess)
┌──────────────┴──────────────┐
│  Your model                 │  OpenRouter · OpenAI · Anthropic · claude-local
└─────────────────────────────┘

One install command. Open WebUI, the Claude Agent SDK, the OpenAI Agents SDK, LiteLLM, and FastAPI are all bundled as required dependencies. No optional extras for the runtime.

A minimal AGENTS.md

---
name: code-reviewer
description: Reviews a code diff. Ranks the top three issues by severity.
model: openrouter/anthropic/claude-haiku-4.5
---

You review code. When the user pastes a diff or a file, identify the top
three issues ranked by severity: correctness first, then security, then
readability.

For each issue, cite the line number and explain the fix in one sentence.
Skip style nits unless the user asks for them. If the code looks clean,
say so in one line and stop.

That is the whole hub. One file. No sub-agents, no skills, no knowledge needed. Drop it in a folder, run hubzoid run ., and you have a code reviewer at http://localhost:3080.

Editing your hub

Your hub is one folder. Six things to know.

1. Pick your model. Default .env uses MODEL=claude-local (no key needed if claude login is done). To switch to OpenRouter / OpenAI / Anthropic, uncomment a stanza in .env and paste a key.
2. Write the main agent. Open AGENTS.md. The body is the system prompt. YAML frontmatter sets name, description, and optional model.
3. Sub-agents. One folder per sub-agent under agents/. Each has its own AGENTS.md. Frontmatter tools: [...] whitelists which tools the sub-agent may call.
4. Skills. One folder per playbook under skills/, each with a SKILL.md. The main agent loads them on demand via load_skill(name).
5. Knowledge. One markdown file per topic under knowledge/. Reached via read_knowledge(name).
6. Tools and connectors. Drop Python files with @function_tool in tools_local/. Edit connectors/.mcp.json to plug in MCP servers.

Folder names are case- and plural-flexible. skills/, Skills/, and skill/ all work. Same for agents/, knowledge/, tools_local/, connectors/. Restart with the same command. Changes are picked up on the next start.

Multi-hub agents repo

Run hubzoid init more than once in the same directory and you get a Samarth-style multi-hub layout with one parent requirements.txt:

mkdir my-agents && cd my-agents
hubzoid init devops-agent       # creates ./devops-agent + ./requirements.txt + ./.gitignore + ./README.md
hubzoid init support-agent      # creates ./support-agent only; parent files left alone
hubzoid init research-agent     # creates ./research-agent only

Each hub is independent: its own .env, its own port, its own user database. The parent files are written only on the first init in a fresh directory (empty or containing only dotfiles / README / requirements.txt / LICENSE). Idempotent and non-destructive afterward.

Providers

Pick one stanza in .env. See docs/providers.md for more detail.

# OpenRouter (one key, many models)
OPENROUTER_API_KEY=sk-or-v1-...
MODEL=openrouter/anthropic/claude-haiku-4.5

# OR OpenAI
OPENAI_API_KEY=sk-...
MODEL=openai/gpt-4o-mini

# OR Anthropic
ANTHROPIC_API_KEY=sk-ant-...
MODEL=anthropic/claude-haiku-4-5

# OR Claude local (uses your installed `claude` CLI + Pro/Max subscription)
# Requires `claude login` first. No API key needed.
MODEL=claude-local
# MODEL=claude-local/sonnet       # pin Sonnet
# MODEL=claude-local/opus         # pin Opus
# MODEL=claude-local/haiku        # pin Haiku

The MODEL string tells LiteLLM which provider to call, and the matching key must be set. The exception is MODEL=claude-local: instead of LiteLLM, hubzoid drives the Claude Agent SDK against your locally installed claude CLI, so auth and billing flow through your existing Pro/Max subscription. Same hub folder, same tools, same skills. Only the LLM and auth path differ.

Pre-shipped tools

Every hub gets these tools for free.

Tool	What it does
read_file(path)	Read a file under the hub directory.
list_files(glob)	List files matching a glob.
write_artifact(filename, content)	Write a file under output/<session>/.
list_skills()	Menu of skills in the hub.
load_skill(name)	Read a skill's full body on demand.
list_knowledge()	Menu of knowledge documents.
read_knowledge(name)	Read a knowledge document's full body.
remember(fact, scope)	Save a fact to durable memory.
recall(query, scope)	Look up saved facts.
forget(id, scope)	Delete a saved fact.
render_jinja(template, context_json)	Render a Jinja2 template.
http_get(url)	Fetch a URL (honors HTTP_ALLOWLIST).
web_search(query)	DuckDuckGo search. No API key.

Custom tools dropped into tools_local/*.py are auto-discovered.

MCP connectors

MCP connectors are per-hub. Each hub has its own <hub>/connectors/.mcp.json alongside its AGENTS.md. Two hubs in the same agents-repo connect to completely different MCP servers because each loads its own config independently. There is no parent-level shared MCP file by design: agents are independent products with their own scope.

Edit demo-hub/connectors/.mcp.json (or whatever your hub is named):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "./workspace"]
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GH_TOKEN}"}
    }
  }
}

${VAR} references in any string field resolve against the environment at boot. The same .mcp.json is honored by both the OpenAI Agents and Claude Agent runtimes.

CLI

hubzoid init [NAME]              Scaffold a new hub folder under the current directory.
                                   NAME defaults to "demo-hub".
                                   Also drops requirements.txt / .gitignore / README.md
                                   at the parent on first run if the directory looks fresh.
hubzoid run [PATH]               Start the FastAPI bridge plus Open WebUI for a hub.
  --port INT                       Open WebUI port (default 3080).
  --bridge-port INT                FastAPI bridge port (default 8000).
  --no-ui                          Bridge only, no Open WebUI.
hubzoid doctor [PATH]            Validate hub config and report issues.
hubzoid test [PATH]              Send one prompt to the agent and print the response.
hubzoid version
hubzoid --help

PATH defaults to . for run / doctor / test. python -m hubzoid ... also works as an alternative invocation.

Run from source

For contributors or anyone who wants to read or extend the framework code.

git clone https://github.com/hubzoid/hubzoid.git
cd hubzoid
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
hubzoid run demo-hub

The repo ships with demo-hub/ at the root as a working starter. Its .env is git-ignored but the template includes sensible defaults (MODEL=claude-local).

Open standards

Spec	Used at
AGENTS.md	<hub>/AGENTS.md, <hub>/agents/<n>/AGENTS.md
SKILL.md	<hub>/skills/<n>/SKILL.md
MCP	<hub>/connectors/.mcp.json

Hubs are portable across any tool that adopts these specs (Claude Code, Cursor, Codex, Copilot, Gemini CLI, VS Code).

Roadmap

• v0.2 Current. PyPI release with bundled Open WebUI + Claude Agent SDK; OpenAI Agents and Claude Agent runtimes; AGENTS.md, SKILL.md, MCP loaders; OpenRouter, OpenAI, Anthropic, claude-local providers.
• v0.3 Per-hub branding, auth-on path, native-venv production deployment docs, Playwright UI test tier.
• v0.4 Background and scheduled workflows via WaveAssist Cloud (separate product, opt-in).
• Later Slack and Telegram chat surfaces. Mem0 / Zep memory backends.

Non-goals: voice and realtime, visual agent builder.

Hubzoid as a service

This is the open-source framework. hubzoid.com is the consulting practice that deploys role-scoped hubs for mid-enterprise organizations in six weeks, fixed scope, fixed price. The framework is the substrate; the practice ships the deployment.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome.

License

MIT.