Hanumate is a headless TypeScript framework for building autonomous AI coding agents. Open source, extensible, and built for production.

Whether you're building a single developer tool or orchestrating a fleet of agents in production, Hanumate provides the building blocks you need: universal LLM routing, native MCP support, sandboxed code execution, persistent state, watchdog monitoring, and Bors-style quality gates.

Install the core package using your preferred package manager:

npm install @hanumate/core
# or
yarn add @hanumate/core
# or
pnpm add @hanumate/core

You'll need Node.js 18+ and an API key for your preferred LLM provider.

Here's a minimal example that ties everything together:

import { createAgent } from "@hanumate/core";

const agent = createAgent({
  llm: {
    provider: "openai",
    model: "gpt-4o",
    apiKey: process.env.OPENAI_API_KEY,
  },
  mcp: {
    servers: ["./my-mcp-server.js"],
  },
  execution: {
    sandbox: "daytona",
    maxMemory: "512mb",
    timeout: 30000,
  },
  state: {
    adapter: "postgres",
    resumeOnCrash: true,
  },
  watchdog: {
    maxIterations: 1000,
    timeoutMs: 300000,
    onStuck: "escalate",
  },
  gates: {
    queue: true,
    bisect: true,
    blockOnFailure: true,
  },
});

await agent.run({
  task: "Implement a REST API endpoint for user authentication",
});

Hanumate is built around a modular, extensible architecture. The core agent engine orchestrates LLM interactions, tool execution, and state management through a clean, composable API.

Each agent goes through a defined lifecycle: initialization, planning, execution, tool calls, state updates, and termination. Hooks let you intercept and modify behavior at each stage.

Tools are functions the agent can call to interact with the outside world. Define custom tools with TypeScript, or use pre-built integrations via MCP servers.

State is managed through a persistent adapter system. Choose from PostgreSQL, SQLite, Redis, or build your own adapter. State survives agent restarts and crashes.

Connect to OpenAI, Anthropic, MiniMax, Groq, Ollama, or any OpenAI-compatible endpoint. Route requests across multiple providers simultaneously for cost, latency, and capability optimization — no code rewrites needed.

import { createAgent } from "@hanumate/core";

const agent = createAgent({
  llm: {
    provider: "openai",
    model: "gpt-4o",
    apiKey: process.env.OPENAI_API_KEY,
  },
});

Swap models with a single config change. Hanumate handles the provider-specific details automatically.

Native MCP client built in. Connect to MCP servers for tools, resources, and prompts. Full tool-call orchestration with automatic schema parsing, retry logic, and streaming support.

const agent = createAgent({
  mcp: {
    servers: ["./my-mcp-server.js"],
  },
});

Run agent-generated code in firecracker microVMs via Daytona or E2B. Full filesystem isolation, network sandboxing, and resource limits. Execute untrusted code safely.

const agent = createAgent({
  execution: {
    sandbox: "daytona",
    maxMemory: "512mb",
    timeout: 30000,
  },
});

Hooks, Beads, and Convoys track agent work across restarts and network failures. Never lose context when an agent crashes. State survives timeouts, redeployments, and reboots.

const agent = createAgent({
  state: {
    adapter: "postgres",
    resumeOnCrash: true,
  },
});

Automatic liveness probes, session timeout escalation, and circuit breakers. Detect stuck loops, token-hammering, and resource exhaustion before they cascade.

const agent = createAgent({
  watchdog: {
    maxIterations: 1000,
    timeoutMs: 300000,
    onStuck: "escalate",
  },
});

Merge queue with bisecting for CI-integrated agent testing. Queue pending agent tasks, run validation suites in parallel, and auto-retry failed bisects.

const agent = createAgent({
  gates: {
    queue: true,
    bisect: true,
    blockOnFailure: true,
  },
});

Full configuration options are available in the Configuration reference. All options are TypeScript-typed and include JSDoc documentation.

The Agent API provides methods for creating, running, pausing, and resuming agent sessions.

Hooks allow you to intercept and modify agent behavior at key points in the execution lifecycle. Events provide visibility into agent activity for logging, monitoring, and debugging.

Daytona provides firecracker-based sandboxed execution for Hanumate agents. Full isolation, fast cold starts, and enterprise-grade security.

E2B offers cloud-based sandboxed execution with a managed runtime. Great for teams that want zero-infrastructure code execution.

Run agents locally without any cloud dependency. Ideal for air-gapped environments, development, and testing.