hummbl-agent

A governed control plane for AI agent systems -- registry-first skill management, deterministic policy routing, and auditable execution across any LLM runner.

---

Quick start

git clone https://github.com/hummbl-dev/hummbl-agent.git
cd hummbl-agent
pnpm install
pnpm run lint:schemas          # validate skill schemas
scripts/e2e-validate.sh        # end-to-end validation

---

What it does

Most agent frameworks let LLMs decide what to run and how. hummbl-agent inverts that -- policies decide, agents execute.

Primitive	What it does	Location
Kernel	Type-safe agent, task, tool, and state definitions	packages/kernel/
Control Plane	JSON policy DSL, deterministic compilation, emits ControlDecision	packages/control-plane/
Router	Routes skills to runners based on policy + capability matching	packages/router/
Runners	Adapter layer for 10 LLM backends (Claude, Codex, Gemini, Grok, Ollama, etc.)	packages/runners/
Governance	Policy schemas, compliance claims, audit logs	packages/governance/
Skill Registry	75+ skills with SHA-256 integrity, CI-validated manifest	skills/
Gateway	Adapters for Anthropic, OpenAI, and communication channels	packages/gateway/
Schemas	JSON Schema definitions for skills, decisions, and inter-agent requests	schemas/

---

Why this exists

Agent tooling today has a trust problem. Most frameworks give the model full authority over tool selection, execution order, and state mutation. That works for demos. It breaks in production.

hummbl-agent is built on three principles:

1. Registry-first. The local skills/MANIFEST.json is the only source of truth. No external registries, no dynamic resolution, no ambient authority. Every skill is hash-verified.

2. Policy-bounded. A JSON policy DSL defines what can run, where, and under what constraints. The control plane compiles policies into deterministic ControlDecision objects. No heuristics, no planning, no LLM-in-the-loop for routing.

3. Vendor-agnostic. Claude Code, Codex, Gemini, Grok, Ollama, and five other runners are interchangeable adapters. Swap the runner, keep the governance. No vendor lock-in at the execution layer.

The control plane dispatches. It does not execute. This separation means you can audit every decision, replay any run, and prove what happened.

---

Install

# requires Node 18+ and pnpm
pnpm install

# build all packages
pnpm -r build

# run tests
pnpm -r test

Individual packages are scoped under @hummbl/:

cd packages/kernel && npm test
cd packages/control-plane && npm test
cd packages/router && npm test

---

Project structure

hummbl-agent/
  packages/
    kernel/           # Core types (agent, task, tool, state, memory)
    control-plane/    # Policy DSL + deterministic evaluation
    router/           # Skill-to-runner routing engine
    runners/          # 10 LLM backend adapters
    runtime/          # Python runtime bridge
    governance/       # Policy schemas + compliance
    gateway/          # External service adapters
    adapters/         # Communication + LLM adapters
    vendor-bridge/    # Vendor path mapping (non-authoritative)
  skills/             # Canonical skill registry + MANIFEST.json
  schemas/            # JSON Schema definitions
  scripts/            # CI + validation scripts
  tests/              # Integration + e2e tests

---

Related projects

Project	Description
hummbl-governance	Governance framework and policy primitives (pip install hummbl-governance)
HUMMBL Research Corpus	Research notes on agent governance, Base120, and multi-agent coordination
hummbl.io	Company site

---

Contributing

See CONTRIBUTING.md for branch naming, commit conventions, and PR guidelines.

---

License

Proprietary. Copyright (c) 2026 Reuben Bowlby and Daniel Matha. All rights reserved. See LICENSE.