HazelJS Overview

HazelJS is a TypeScript backend whose primary product is Agent OS — durable AI agents inside the same DI/HTTP app as your APIs: DNA packages, crash-safe HITL, Skillgate, Gatekeeper, Agent VM, and local apply. Framework packages (HCEL, RAG, workflows) exist when you need them — they are not the wedge.

Quick Reference

• Purpose: Ship durable agents in a TypeScript backend with packaging (DNA), governance (Skillgate), authorization (Gatekeeper), reversible tools (Agent VM), and crash-safe process (AgentRun HITL) — without Nest + LangGraph + workers.
• When to use: Backend TypeScript / Node teams putting AI into existing APIs, or greenfield agent products that need DNA / HITL / Skillgate / local apply.
• Key concepts: Agent OS, DNA ≠ tools, Store vs platform vs run, Skillgate, Gatekeeper, Agent VM, local apply, Modules / Controllers / DI (framework layer).
• Primary path: Clone Meridian — store:sync → platform:sync → npm run dev.
• Also available: hazel agent new (Agent OS scaffold); HCEL chains (@hazeljs/​ai), RAG, workflows — brownfield / secondary.
• Dependencies: Node.js 18+, TypeScript with experimentalDecorators. @hazeljs/​core loads reflect-metadata automatically — do not install or import it in your app.

Quick Start — Agent OS (Meridian)

git clone https://github.com/​hazel-js/​hazeljs-meridian-ops.git
cd hazeljs-meridian-ops
npm install
npm run store:sync      # DNA packages + lockfile
npm run platform:sync   # Apply Definitions /​ Deployments (does not restart Node)
npm run dev             # Chat with real @Tool handlers + HITL

Also: Agent OS · Agent OS guide · What is an Agent OS? · Skillgate

Agent OS scaffold (smaller than Meridian)

npx @hazeljs/​cli agent new my-desk --template=agent-os
# templates: bare | agent-os | skillgate

Also — framework app template

HTTP + HCEL / RAG scaffold. Useful for framework onboarding — not the Agent OS teaching path (no DNA / Store / Skillgate / HITL / apply).

npx @hazeljs/​cli g app my-app --template=ai-native

Prefer Meridian when you need DNA, crash-safe HITL, Skillgate, or local apply.

What Is HazelJS?

HazelJS is the Agent OS for TypeScript backends. The Agent Runtime is the kernel; Agent OS is how you package, govern, authorize, test, and operate agents in the same HazelApp as your APIs.

You do not assemble Nest + LangGraph + a worker fleet.

Architecture Mental Model

Agent OS execute

flowchart TD
  A[Goal] --> B[AgentRuntime.execute]
  B --> C[DNA / policy overlay]
  C --> D[Loop: plan execute critique]
  D --> E{Tool call}
  E -->|read| F[Skillgate skill]
  E -->|write| G[Gatekeeper + HITL]
  G -->|durableSuspend| H[Approve / resume]
  F --> I[Agent VM optional undo]
  H --> I
  I --> J[Inspector timeline]
  J --> K[Result / contract / recovery]

HTTP request flow (same app)

flowchart LR
  A[Request] --> B[Router]
  B --> C[Middleware]
  C --> D[Guards]
  D --> E[Interceptors]
  E --> F[Pipes]
  F --> G[Controller]
  G --> H[Service]
  H --> I[Response]

Agents and REST share the same modules, DI container, and process.

Core Philosophy

• Agents as packages — DNA is prompt + policy + contracts, not tool implementations. Hot-reload without restarting Node.
• Governed skills — Skillgate turns OpenAPI into allowlisted skills; writes need approval by default.
• Fail-closed tools — Gatekeeper authorizes every tool call. Not a prompt guardrail.
• Crash-safe HITL — durableSuspend / approveAndResume survive process restart.
• Same backend — Controllers, DI, auth, and agents in one TypeScript app.
• Test like production — describeAgent CI, eval golden sets, Inspector timelines.

Key HazelJS Packages

See Installation for the complete package list.

When to Use HazelJS

Use HazelJS When

• Shipping durable agents beside REST / GraphQL in TypeScript
• You need DNA packages, Skillgate, crash-safe HITL, or Agent VM undo
• You want CI (describeAgent), Inspector timelines, and Gatekeeper on tools
• You want one backend instead of Nest + LangGraph + workers

Consider Alternatives When

• Frontend-only (use Next.js, Remix)
• A single serverless function with no shared agent process
• Python-only AI ecosystem (LangChain, LlamaIndex)
• A static site or CRUD API with no agents

Decision Guide: HazelJS Packages

Next Steps

• Meridian — Clone path: store → platform → dev
• Agent OS — Product lander
• Agent OS guide — DNA, HITL, Skillgate, local apply
• Skillgate — OpenAPI → governed skills
• Installation — Packages and tsconfig
• CLI — hazel agent new and generators (secondary to Meridian)
• Agent Package — Kernel APIs
• Testing — describeAgent

Related Pages

• What is an Agent OS? — Category definition
• Agent VM — Reversible tools
• Gatekeeper — Fail-closed authorization
• Core Package — HTTP / DI foundation
• Concepts & Glossary — Terminology