extend-harness

Extending harness

Harness is a state follower; everything else is plugins discovered at runtime from .harness/ directories. To extend the running agent — yourself — drop an executable into the right place. The next loop iteration picks it up; no restart needed (_refresh_sources runs every turn).

Where to put extensions

Discovery walks from CWD up to /, collecting every .harness/ directory. For same-named files, most-local wins. Pick scope based on lifetime and audience:

Scope	Location	Use when
User-global	~/.harness/	Available everywhere; personal preferences, secrets
Project	<repo>/.harness/	Committed with the repo, scoped to that project
Subdir	<dir>/.harness/	Narrower scope inside a monorepo

Inside any .harness/:

commands/         # CLI subcommands (hs <name>)
tools/            # tools the model can call
hooks.d/<stage>/  # pipeline hooks; sorted by NN- prefix
providers/        # LLM API adapters (binary or .conf variant)
prompts/*.md      # appended to the system prompt
skills/<name>/    # on-demand instruction packs (SKILL.md)
plugins/<name>/   # plugin packs with the same layout

AGENTS.md follows the agents.md standard — placed at the parent of the .harness/ directory, not inside it.

Tools (the most common extension)

A tool is an executable responding to three flags. Drop it at .harness/tools/<name> and chmod +x.

#!/usr/bin/env bash
set -euo pipefail
case "${1:-}" in
  --schema) cat <<'JSON'
{"name":"web_get","description":"GET a URL and return body",
 "input_schema":{"type":"object",
                 "properties":{"url":{"type":"string"}},
                 "required":["url"]}}
JSON
    ;;
  --describe) echo "GET a URL" ;;
  --exec)
    url="$(jq -r '.url' < /dev/stdin)"
    curl -fsS "$url"
    ;;
esac

• Stdout becomes the tool result. Stderr → HARNESS_LOG. Non-zero exit marks the result as error: true.
• Tools run in HARNESS_CWD (the session's original working directory).
• Any language: see ../../../../examples/tools/web_fetch for a Python example.