Base Harness — AI skill for Claude Code

base-harness

A minimal, reliable, **provider-agnostic AI agent harness** in TypeScript.

The language model is just the "brain". Everything that makes it useful — memory, tools, permissions and a verification loop that doesn't call anything _done_ until the tests pass — is the **harness** you build around it. This repo is a small, readable, didactic implementation of exactly that, meant to be read end to end.

It runs against the **Anthropic API** or a **local, free model via Ollama** by editing a single file. It ships with the local (Ollama) option active, so you can try it with no API key and no cost.

Didactic base, not a production tool. See [Limitations](#limitations).

What's inside

• The agentic loop (runAgent) — the ReAct cycle: send context + tools → the model decides → the harness runs the tool → observe → repeat until the model is done. An agent is just model + harness.
• Tool registry — one place where every tool registers its schema (what the model sees) and its handler (what runs). Importing the barrel wires them up.
• File and terminal tools — read / write / edit files, and run shell commands.
• Guardrails — a workspace path guard (the agent can't escape ./workspace) and a permission guard that blocks destructive commands and asks a human to confirm. Whatever the agent reads is treated as data, never as instructions.
• Memory — working memory trimmed to fit the context window, plus cross-session progress persisted to disk (PROGRESS.md).
• System prompt from the repo — the agent's rules live in AGENTS.md, not in a buried constant.
• Verification — the source of truth is running the tests, not the model's word. A layered ladder (unit → integration → E2E) stops at the first red layer.
• Feature list (WIP=1), maker-checker graph, observability (a JSONL event stream) and a clean session handoff.

Requirements

• Node.js 20+ (uses the built-in test runner and tsx).
• O