The Hub
The Hub is the folder behind every Hubzoid agent. It holds the instructions, knowledge, skills and tools that chat, workflows and connected assistants share.
A Hub is a folder, usually in Git, that holds what one agent needs to do its work: instructions, knowledge, skills, sub-agents and the tools it may call. Every surface that uses the Hub, from chat to scheduled work and assistants connected over MCP, builds on the same files, so you provide context once.
Why it matters
Context takes effort to build. Without a Hub it ends up copied into prompts, chat histories and tool settings, and each copy drifts. With a Hub, a rule changes in one file and every surface uses the new rule.
"Provide context once" does not mean everyone sees everything. Each surface keeps its own history and access rules, and restricted tools run only for the people and workflows granted them.
The smallest Hub
hubzoid init my-hub writes a starter for Kestrel & Oak, a fictional home-goods shop. Two files do most of the work. The instructions:
---
description: A starter assistant for Kestrel & Oak, a fictional home-goods shop. Make it yours.
suggestions:
- A customer wants a refund 40 days after delivery. What can we offer?
- Who has to approve a $650 order?
- When is support open?
---
You are the team assistant for Kestrel & Oak, a fictional home-goods shop
used as Hubzoid's starter. Answer from the files in `knowledge/` and name the
file you used. If they do not answer the question, say so instead of
guessing. Keep answers short.And the knowledge it answers from:
# House rules
- **Refunds.** A customer can return an unused item within 30 days of
delivery for a full refund. After 30 days we offer store credit or a
repair, not a refund.
- **Large orders.** An order over $500 needs a manager's approval before it
ships.
- **Support hours.** Support answers from 09:00 to 18:00 UTC, Monday to Friday.Ask about a refund 40 days after delivery and the agent reads house-rules.md, answers that store credit or a repair is possible, and names the file. Change the rule in the file and the answer changes, in chat, in scheduled work and in Claude Code alike. Project structure lists every file the starter writes.
Video lesson 2 · 3:15Knowledge and skills: how AI agents use your business knowledgeGive an agent the right knowledge and procedure for a task.
What a Hub holds
Read as one agent, a Hub is a definition with two sides: what the agent knows and what it can reach. Hubzoid supplies the surfaces and services around it.
What it knows
Knowledge
knowledge/raw_data/Reference documents read on demand, and raw material searched as text.
Skills
skills/Procedures loaded when a request matches their description.
Definition
AGENTS.mdagents/
Who the agent serves, its job and its rules, plus any sub-agents.
What it can reach
Tools
tools_local/Your Python functions, beside the built-in tools.
Connections
connectors/restricted/Live systems through MCP servers, and restricted tools that run only with a permission.
What Hubzoid provides
- Surfaces
- Web app
- Your own app
- Slack
- Telegram
- OpenAI-compatible API
- MCP
- Webhooks
- Services
- Built-in tools
- Workflow engine
- Sign-in and grants
- Activity log
- Settings
- Evals
Every part, its files and how it reaches the agent
| Part | Files | How it reaches the agent |
|---|---|---|
| Instructions | AGENTS.md | The body is the system prompt for every run. |
| Knowledge | knowledge/**/*.md | Listed by name and description in the system prompt. Read in full with read_knowledge when relevant. |
| Skills | skills/*.md, skills/<name>/SKILL.md | Listed in the system prompt. Loaded with load_skill when a request matches. |
| Sub-agents | agents/*.md, agents/<name>/AGENTS.md | Loaded as skills, or called as delegates on their own model. |
| Tools | Built-in tools, tools_local/*.py, connectors/.mcp.json | Offered to the model as callable tools. |
| Restricted tools | restricted/*.py | Offered only to callers with the matching permission. Checked again at call time. |
| Unstructured data | raw_data/ | Searched with grep_data and read with read_file. |
| Recurring work | schedule/*.md, workflows/<name>/*.py | Run on the workflow engine with the same context. |
| Quality checks | evals/*.md | Run against the same agent with hubzoid eval run. |
| Sender lookup | identity/access.py | Optional. Names WhatsApp and Telegram senders whose numbers are not recorded in Settings. Grants nothing. |
How it works
Chat uses the agent the bridge builds from the Hub folder when it starts. Scheduled tasks and hub.call_agent build it again for each run, so they pick up edits without a restart. hubzoid reload my-hub checks the folder and restarts a running Hub so every change takes effect.
- AGENTS.md body
- Runtime addendum
- Tool registry
- Access guard
- Model call
Knowledge and skill bodies are not in the system prompt. The model sees the menus and loads what it needs, which keeps prompts small as a Hub grows.
What each part of the prompt and tool list contains
- Instructions. The
AGENTS.mdbody is the start of the system prompt. - Runtime addendum. Hubzoid appends the Hub name, runtime, model and date, the menu of knowledge documents and skills (name and description only), any delegates, and short guidance on using tools. Set
auto_addendum: falsein theAGENTS.mdfrontmatter to send the body alone. - Tool registry. Built-in tools, then your
tools_local/tools (a local tool with a built-in's name replaces it), then restricted tools, which win any name conflict. MCP servers fromconnectors/.mcp.jsonjoin beside them. - Access guard. Each restricted tool is wrapped so that a caller without the permission does not see it and is refused if they call it anyway, with the decision recorded.
- The turn itself. The conversation arrives as the prompt. In the web app, the person's own notes come first. With
claude-localandcodex-local, Hubzoid also names the signed-in person, so the model does not mistake the CLI's login for the user.
Instructions
AGENTS.md is written for the model: who it serves, what it is responsible for, how to use the Hub's knowledge and tools, and what to refuse. Keep facts that change in knowledge/ and procedures in skills/, and point to them by name. Design an agent shows how to write them.
Knowledge
A knowledge document is Markdown with optional name and description frontmatter. The description is what the model sees in the menu, so write it as a statement of when the document is useful. Every *.md under knowledge/ is loaded, subfolders included, and the name defaults to the file name.
When edits take effect, raw data and personal sources
read_knowledge and list_knowledge read the folder from disk on every call, so an edited document is used by the next call. The menu in the chat agent's system prompt refreshes when the Hub restarts.
Use knowledge/ for reference material the agent should read and quote. Use raw_data/ for large or unedited material, such as exports and code checkouts, that the agent should search with grep_data rather than read whole. People can also keep their own collections of files and pages under Settings → Sources, which the agent searches with search_sources and cites. See memory and history.
Skills
A skill is a named procedure with a name and a description. The model loads it with load_skill(name) when a request matches the description, then follows it. A name defined in an earlier place wins:
skills/in the Hub.- Sub-agents in
agents/that run as skills. - Skills shipped with Hubzoid, such as
dashboard, which builds a single-file HTML dashboard in chat.
Tools
Every Hub has built-in tools. tools_local/ adds your own Python tools, connectors/.mcp.json adds MCP servers, and administrators can add connectors that each person connects with their own account.
Where tools come from
Built-in tools
Files, knowledge, sources, skills, search, the web, workflows, reports and access.
Your tools
tools_local/*.pyA tool with the name of a built-in replaces it.
Restricted tools
restricted/*.pyWrapped in the access guard. They win any name conflict.
One tool registry
Name, description, arguments and code, written once.
How each caller sees it
OpenAI Agents SDK
Function tools on the agent.
Claude Agent SDK
mcp__hubzoid__<name>One in-process MCP server.
Local Codex
Dynamic tools that Hubzoid runs for Codex.
Connected assistants
/mcpThe same tools without the chat-only ones, the memory tools,
call_jevand delegates.
Beside the registry
connectors/.mcp.jsonHUBZOID_BROWSERmcp__my_<id>__<tool>
MCP servers, the shared browser and connectors added in Settings, used by the Hub agent in chat, tasks, workflows and evals. They are not passed on to connected assistants.
The model only ever asks for a tool. Architecture follows one call through the bridge. The built-in tools reference lists every argument and limit. Tools and connectors shows how to write a local tool and add an MCP server or a connector.
The built-in tools by group
The built-in tools fall into a few groups:
- Files, knowledge and skills:
read_file,list_files,list_knowledge,read_knowledge,search_sources,list_skills,load_skillandgrep_data. File tools stay inside the Hub folder and refuse private paths such asrestricted/,.hubzoid/and.envfiles. - Chat files and the web:
write_artifact,read_upload,http_get,web_searchandcurrent_time. - Memory:
save_memoryandremove_memoryfor a person's own notes, andrememberandpropose_hub_changefor shared changes when in-app editing is on. - Workflows, reports and schedules:
run_workflow,my_reports,repeat_request,schedule_workflowand their companions, each for people who hold the matching capability. - Access:
who_has_access,explain_access,propose_access_changeand their companions, for people with Manage access from chat. - Scheduled tasks only:
run_git,write_hub_file, andpublish_artifactandsend_emailwhen the task opts in.
Restricted tools
Put a tool in restricted/ when only some people or workflows should run it. The file name is the permission: every tool in restricted/ledger.py needs the ledger permission. Hubzoid enforces this in code, outside the model. Grants are made in Settings or with hubzoid grant. See restrict a tool.
How restricted tools are checked, hidden, recorded and given secrets
- Every call is checked when it runs, on all three runtimes and over MCP, and refused unless the caller holds the permission on a surface allowed to reach restricted tools.
- The tool is also hidden from callers who lack the permission.
- Every allow and deny decision is recorded before the call runs. A call whose decision cannot be recorded does not run.
- Secrets for these tools go in
restricted/.env. They are loaded into the process environment, and the agent's file tools cannot read the folder.
The same Hub on every surface
| Surface | What it uses from the Hub |
|---|---|
| Chat (web app, your own app, Slack, WhatsApp, Telegram, API) | The full agent: instructions, menus, all tools the person may use, delegates and the shipped skills. |
| Markdown tasks | The same agent and model, plus tools that exist only for scheduled runs: run_git, write_hub_file for the paths the task declares, and publish_artifact and send_email when the task opts in. |
| Code workflows | hub.call_agent runs the full agent as the run's account. hub.call_llm is one model call with no tools and no Hub instructions. |
| MCP clients | The tools the person may use, including the knowledge and skill tools and their reports, without the chat-only tools, the memory and hub change tools, call_jev and delegates. The AGENTS.md body arrives as server instructions, and the client's own model does the reasoning. |
Scoping a Hub
A Hub can serve one product, one team or a whole company. Scope it by the context and access that belong together:
- One Hub per team or function when each team has its own knowledge, tools and people, for example finance and operations.
- One Hub per product when several teams need the same product knowledge and tools.
- One company Hub for shared questions such as policies, alongside team Hubs for sensitive work.
Each Hub is independent: its own .env and model, knowledge, tools, schedules and conversations. Its folder name is its access domain, so permissions granted in one Hub do not apply in another.
To run several Hubs behind one sign-in and one web app, list them:
hubzoid run ./finance ./operations ./companyTo keep that list, write it under hubs: in a hubzoid.yaml in the folder that holds the Hub folders, and run plain hubzoid run there. People sign in once and see only the agents they are granted. See running several Hubs.