agent-harness

Leia em português

A production-minded harness for AI coding agents and LLM features.

Getting a model to answer is easy. Getting it to behave inside a real codebase and a real product is the engineering work: what context it gets, which actions it may take, how its output is checked, and what happens when it is wrong. This repository is a working, tested reference for that layer.

What is inside

Architecture and the reasoning behind each choice: docs/architecture.md.

Related MCP server: GoHighLevel MCP Server

Quick start

npm install
npm run test        # 57 tests, no network
npm run example     # inbound message -> typed decision, offline with a mock model
npm run mcp:dev     # start the MCP server on stdio

With ANTHROPIC_API_KEY and HARNESS_MODEL set (see .env.example), the example calls the real model through the same code path.

Open the folder in Claude Code and the harness is active: hooks run on every tool call, the leads MCP server is available, and the skills and subagents are listed.

Example: untrusted text to a safe action

const Decision = z.object({
  intent: z.enum(["purchase", "support", "pricing", "cancel", "other"]),
  confidence: z.number().min(0).max(1),
  action: z.enum(["move_to_qualified", "open_ticket", "send_price_table", "handoff_to_human", "none"]),
  reply: z.string().max(280),
});

const { text } = redactPII(message);
const result = await generateStructured({
  provider,
  schema: Decision,
  instructions: "Triage inbound sales messages and pick one next action.",
  input: quoteUntrusted("whatsapp", text),
});

if (result.ok) {
  const verdict = checkAction(policy, result.data.action); // allow | approve | deny
}

The result is a typed object or a typed failure, never free text, so a queue worker or an API handler can consume it directly.

Design principles

• Enforce, do not ask. Rules that matter live in hooks and permissions, not only in the prompt.

• Small base context. Always-loaded instructions stay short; procedures load as skills when needed.

• Independent review. The agent that wrote a change does not approve it.

• Schemas at every boundary. Model output and external API responses are validated where they enter the system.

• The model proposes, code decides. Side effects go through a policy.

• Deterministic tests. Time, randomness, fetch and the model are injected; the suite runs offline in about a second.

Stack

TypeScript (strict, ESM) · Node.js 20+ · Zod 4 · Model Context Protocol SDK · Vitest · GitHub Actions.

Author

Leandro Silva Ferreira Junior · LinkedIn

Fictitious data only. MIT license.