Agents and models

Every Hub has one main agent, defined by AGENTS.md, and any number of sub-agents in agents/. The model id decides which of three runtimes runs them: the OpenAI Agents SDK with LiteLLM, the Claude Agent SDK with your claude CLI, or local Codex with your codex CLI. The Hub files are the same on each.

The main agentCopy Anchor Link

AGENTS.md at the Hub root is the main agent. Its body is the system prompt, and its frontmatter sets the name, description, model and chat suggestions. Every surface talks to the main agent. It holds the full tool registry and decides when to load a skill or call a delegate.

---
name: ops-desk
description: Answers operations questions and prepares the weekly review.
model: claude-local
suggestions:
  - What changed in stock this week
---

You help the operations team. Use the knowledge documents for thresholds,
and load the weekly-review skill when someone asks for the weekly review.

The project structure page lists every frontmatter field.

Sub-agentsCopy Anchor Link

A sub-agent is a Markdown file in agents/, either agents/<name>.md or agents/<name>/AGENTS.md when it has supporting files. It uses the same frontmatter as the main agent, plus tools.

---
name: researcher
description: Writes a short, sourced brief when someone asks for research on a topic.
model: claude-local/opus
tools: [web_search, http_get, read_knowledge]
---

Research the topic you are given. Use at most five sources and cite each one.
Return a brief of no more than 300 words with the sources listed at the end.

Skill or delegateCopy Anchor Link

Hubzoid classifies each sub-agent when it builds the agent. The rule depends only on the sub-agent's model: compared with the Hub's model.

For example, on a Hub running claude-local (Sonnet), the researcher above has model: claude-local/opus, so it becomes a delegate that runs on Opus. On a Hub running openai/gpt-4o-mini, a sub-agent with model: openai/gpt-4o is a delegate, and one with model: claude-local/opus is a skill. On a Hub running codex-local, a sub-agent with model: codex-local/<model-id> is a delegate on that Codex model.

A skill-classified sub-agent is added to the skill menu. If a skill in skills/ has the same name, the one in skills/ wins and a warning is logged.

How delegation worksCopy Anchor Link

The main agent keeps control. It calls a delegate within the turn with a brief, the delegate works in isolation on its own model, and its final message comes back as the result. The runtime addendum lists each delegate with its model and tells the main agent to relay the answer faithfully.

Delegates are not exposed over MCP, because an MCP caller brings its own model. There, every sub-agent is a skill. A delegate never receives the person's own personal MCP connections. Only the main agent does.

RuntimesCopy Anchor Link

All three runtimes stream text and tool activity in the same format, record token usage per turn, and use the same access guard. Each one shows the agent only the controlled tools (restricted/ tools, remember, call_jev) the person may use, and refuses any other call. The architecture page shows where the runtime sits in a request.

Choosing the modelCopy Anchor Link

The Hub's model is resolved in this order. The first one set wins.

1. A per-run override: a markdown task's model: frontmatter, or hubzoid schedule run --model.
2. MODEL in the Hub's .env.
3. model: in AGENTS.md.
4. claude-local.

On a claude-local Hub, an override of a bare tier (opus, sonnet, haiku) or a claude-* id stays on the Claude runtime, so model: opus in a task means claude-local/opus. A full id for another engine, such as openai/gpt-4o or codex-local, switches that run to it.

hubzoid init in an interactive terminal checks for a logged-in claude CLI and a logged-in Codex CLI. It writes the only one it finds into the new Hub's .env, or asks once when both are usable. hubzoid init my-hub --model codex-local sets the model without asking. Detection only reads the login status and makes no model call.

ProvidersCopy Anchor Link

For Azure, the part after azure/ is the deployment name you created in Azure, not the underlying model name. For the four key-based prefixes, a missing key stops the agent from building with an error naming the variable. Any other model id is passed to LiteLLM unchanged, and LiteLLM reads that provider's own environment variables.

Tiers for claude-localCopy Anchor Link

An unrecognized pin falls back to Sonnet with a warning in the log, so an unattended run never goes to the CLI with a typo. For a server without an interactive login, mint a subscription token with claude setup-token on a logged-in machine and set it as CLAUDE_CODE_OAUTH_TOKEN in the Hub's .env. The claude CLI must be installed and on the PATH of the user that runs the Hub. The Docker image has no claude CLI, so use a provider key there.

Codex modelsCopy Anchor Link

codex-local uses the Codex CLI's default model. codex-local/<model-id> pins a model the logged-in account can use, and Codex is told not to fall back to another one. Install the pinned CLI and log in as the account that runs the Hub:

npm install -g @openai/codex@0.147.0
codex -c 'cli_auth_credentials_store="file"' login

Other CLI versions are refused until their tool isolation has been reviewed, so upgrade the CLI only with a Hubzoid release that supports it. hubzoid doctor reports the CLI and login as runtime.codex_login. Your Codex account's model access and usage limits still apply. Token counts are recorded, and the cost is an estimate only when the model's price is known. The Docker image has no Codex CLI.

Model settingsCopy Anchor Link

These .env keys apply to the whole Hub.

The configuration reference lists every key.

Models in workflowsCopy Anchor Link

Code workflows call the Hub's models in two ways. hub.call_agent(task) runs the full agent with its tools, skills and knowledge. hub.call_llm(prompt) is a single model call with no tools and no Hub instructions, returning text, JSON or a validated Pydantic object, on LiteLLM models, claude-local and codex-local. Both default to the Hub's model and record a usage row. The experimental hub.call_jev asks TypeSafe's Jev through OpenRouter for typed decisions with its own JEV_OPENROUTER_API_KEY, never the Hub's model key. See the workflow API.

Next stepsCopy Anchor Link

Read this page as Markdown