Architecture
Runtime internals: one JVM process, primitives, turn pipeline, tool loop, extension points. Hive is optional.
Audience and mental model
This page is for developers who will read or change the runtime code. It describes how the pieces fit together internally. If you only operate the runtime, the User Guide concept pages are a better starting point.
The mental model: the runtime is a single long-lived JVM process that owns a workspace volume, exposes a dashboard and one or more channels, and runs a tool loop per turn. All extensibility — skills, plugins, MCP servers — plugs into the same loop.
Bot and Hive
Two components, not a cluster
The product is Bot (the runtime) plus an optional Hive (fleet orchestrator). Bot stands alone; Hive is worth adding only when you run more than one Bot and need coordinated approvals or shared inspection.
GolemCore Bot
One JVM process, one dashboard, one workspace volume. Runs agent sessions, tools, skills, memory, traces, channels, and delayed actions.
Standalone
GolemCore Hive
Separate process that tracks many Bots and provides approvals, lifecycle signals, and read-only cross-runtime inspection. Optional.
Optional
Runtime primitives
Everything inside the runtime is one of these primitives. The rest of the code is plumbing between them.
Session
Persistent conversations with their own tool-call history and state. The unit of work the user interacts with.
Conversation
Turn
One request/response cycle in a session: input, tier resolution, tool loop, persistence, response.
Cycle
Skill
Sticky overlay on a session: instructions plus optional MCP server and variables. Loaded from workspace/skills/.
Behavior
Plugin
Capability pack contributed at startup — tools, channels, voice, RAG backends. Loaded from plugin classpath entries.
Capability
Memory
Structured store with lifecycle (Draft → Confirmed → Updated → Forgotten) and progressive disclosure loading.
State
Model router
Tier-to-model mapping stored in preferences/model-router.json. Resolves abstract tiers to concrete provider+model pairs.
Routing
Channel
Input sources — dashboard chat, Telegram, webhooks, Hive commands. Each channel can start a turn and emits a response event stream.
Input
Trace
Replayable execution snapshots attached to each turn. Stored under workspace/traces/.
Observability
The turn pipeline
A turn follows a strict pipeline. Knowing the order helps when reading the code or debugging unexpected behavior.
1. Channel — receives input, starts a session context
2. Tier select — active skill or session default picks a tier
3. Resolve — model router picks a concrete provider+model
4. Prepare — memory loaded (headers), skills merged, tools declared
5. Tool loop — model ↔ runtime until model stops requesting tools
6. Finalize — response emitted to the channel
7. Persist — session, memory updates, trace written to workspaceEvery stage produces events on the internal event bus. The dashboard and logs are just subscribers — nothing in the pipeline is hidden from instrumentation.
Inside the tool loop
The tool loop is where most of the complexity lives. Each iteration does the same thing:
while (model returns tool_use):
collect requested tool calls
for each tool call:
dispatch to tool registry (core, plugin, MCP)
execute with timeout and sandbox
capture result or error
feed all results back to model
emit model's final assistant messageThe tool registry is the integration point for plugins and MCP servers: both contribute tools into the same registry, and the dispatcher does not care whether the tool is native Java, a plugin-provided adapter, or a JSON-RPC call to an MCP subprocess.
Extension points
There are three places to add functionality to the runtime, in increasing order of coupling to the core code:
Skills
No code change. Write SKILL.md files on disk. Good for per-deployment behavior tweaks, MCP integrations, and cross-skill composition.
Zero-code
Plugins
Compile a plugin against the plugin API, drop the jar on the classpath. Runs inside the Bot process but is loaded dynamically at startup.
In-process
Core changes
Modify Bot itself — new primitives, new pipeline stages, new event kinds. Requires a fork or an upstream PR. Reserve for capability gaps that cannot be closed any other way.
Core
Most real work is a skill. Some of it becomes a plugin. Very little of it becomes a core change.
When Hive is worth it
Hive is a separate process that subscribes to lifecycle events from one or more Bots and adds cross-runtime coordination. The Bot does not depend on Hive at runtime; the Hive connection is configured in preferences/hive.json and can be removed without restarting.
- One Bot, one operator, one dashboard: do not add Hive.
- Multiple Bots that need approval gates or cross-runtime search: Hive earns its keep.
- You want Hive's inspection views but do not need approvals: Hive runs in read-only mode.
What to do next
Related pages
Developer Guide
Contributing
Practical setup for contributing to GolemCore: repositories, local build, branching, PRs, and what CI expects.
User Guide
Model Routing
How the model router turns abstract tier names into concrete model calls, and the priority order that resolves tier conflicts.
User Guide
MCP Servers
How MCP servers are declared in skills, how the runtime manages their lifecycle, and how to debug handshake failures.