@herdctl/core

Core library for herdctl fleet management

Documentation: herdctl.dev

Overview

@herdctl/core is the programmatic foundation for herdctl. Use it to embed autonomous Claude Code agents directly in your Node.js applications - build custom dashboards, integrate with your existing tools, or create entirely new agent orchestration systems.

Installation

npm install @herdctl/core

Quick Start

import { FleetManager } from "@herdctl/core";

// Initialize from config file
const fleet = new FleetManager();
await fleet.initialize();

// Start the fleet
await fleet.start();

// Manually trigger an agent
const result = await fleet.trigger("my-agent", undefined, {
  prompt: "Review the latest changes",
});

console.log(`Job ${result.jobId} started`);

// Stop gracefully
await fleet.stop();

Features

• FleetManager - Core orchestration class for managing agent fleets
• Configuration - Load and validate herdctl YAML configs programmatically
• Job Control - Trigger, cancel, and fork agent jobs
• Scheduling - Built-in scheduler for cron and interval triggers
• Event System - Subscribe to fleet events (job:created, job:completed, etc.)
• State Management - Persistent state for jobs, sessions, and fleet status
• Hook Execution - Run shell commands, webhooks, and Discord notifications

Usage

Loading Configuration

import { loadConfig } from "@herdctl/core";

const config = await loadConfig("./herdctl.yaml");
console.log(`Loaded ${config.agents.length} agents`);

Event Handling

fleet.on("job:completed", (event) => {
  console.log(`Job ${event.job.id} completed for ${event.agentName}`);
});

fleet.on("job:failed", (event) => {
  console.error(`Job failed: ${event.error.message}`);
});

Programmatic Triggers

// Trigger with custom prompt
const result = await fleet.trigger("code-reviewer", undefined, {
  prompt: "Review PR #123 for security issues",
  onMessage: (message) => {
    // Stream agent output in real-time
    if (message.type === "assistant") {
      process.stdout.write(message.content);
    }
  },
});

Documentation

For complete API documentation, visit herdctl.dev:

• Library Reference
• Configuration
• Concepts

Related Packages

• herdctl - CLI for running agent fleets
• @herdctl/discord - Discord connector

License

MIT