leharness is me trying to understand harness engineering by building one myself.
I mostly want to understand the parts that actually matter underneath modern harnesses:
Also, the name exists because I dreamt up the project while I was in Paris.
The CLI is experimental and published as leharness on npm. It installs one
command: lh.
Install globally:
npm install -g leharness
lh --help
Run without installing:
npx leharness@latest --help
Update an existing global install:
npm install -g leharness@latest
Start an interactive session:
lh
Run one prompt and exit:
lh "summarize this repo"
Use OpenAI:
export OPENAI_API_KEY=...
lh --provider openai
Use DeepSeek:
export DEEPSEEK_API_KEY=...
lh --provider deepseek
lh --provider deepseek --model deepseek-v4-pro
Use Ollama:
ollama pull qwen3.6:27b-coding-nvfp4
lh --provider ollama
In the TUI, /model opens a client-side model picker and /effort opens a
client-side reasoning effort picker for supported models:
/model
/effort
See lh --help for the full set of options and environment variables.
The CLI also reads a repo-local .env file before provider setup.
Sessions are saved under .leharness/sessions in the current working directory
unless LEHARNESS_HOME is set. Workspace-owned skills can live under
.leharness/skills/<name>/SKILL.md; inherited workspace skill locations
.agents/skills and .claude/skills are also discovered.
For local package development:
pnpm install
pnpm package:verify
Most of the interesting agent repos mix together:
That is useful if you want the whole product, but it makes it harder to study the lower-level harness decisions cleanly.
So this repo is basically me taking notes, doing comparative research, and hopefully ending up with a core I can improve one feature at a time without having to keep rewriting the foundation.
These are the main architectural bets I want the base layer to rest on:
At the boundary, the flow should look like:
ingress -> invocation -> append invocation events -> run session loop
Simple parent loop
One clear control loop that stays small, readable, and focused on orchestration.
while (true) {
const events = loadEvents(sessionId)
const session = projectSession(events)
if (shouldCompact(session)) {
compact(session)
continue
}
const prompt = buildPrompt(session)
const modelOutput = await callModel(prompt)
const toolResults = await executeToolCalls(session, modelOutput.toolCalls)
if (!shouldContinue(session, modelOutput, toolResults)) break
}
Generic core, thin wrappers
The harness core should stay generic. CLI, coding-agent defaults, web/TUI, bots, and future products should sit on top instead of leaking into the loop.
Event-sourced sessions
The event log should be the source of truth for what happened in a session.
{"type":"invocation.received","kind":"message","text":"fix the failing test"}
{"type":"step.started","step_id":"step_1"}
{"type":"model.completed","tool_calls":[{"tool":"bash","execution":"auto"}]}
{"type":"task.started","task_id":"task_42","kind":"bash"}
{"type":"task.completed","task_id":"task_42","summary":"2 tests still failing"}
Session derived from events
The session should be rebuilt from events, and everything else should be derived from that session.
const session = projectSession(events)
const prompt = buildPrompt(session)
const notifications = projectTaskNotifications(session)
const artifacts = projectArtifacts(session)
Background as a first-class runtime feature
The agent should be able to send work off, keep moving, and react when completions come back. That means task-like operations should be able to finish inline or return a durable handle when they need to keep running.
const testRun = await bash({
command: "npm test",
execution: "auto",
})
// inline:
// { status: "completed", output: "..." }
// background:
// { status: "started", task_id: "task_42" }
onTaskCompleted(task) {
appendEvent({
type: "task.completed",
task_id: task.id,
session_id: task.sessionId,
})
markSessionRunnable(task.sessionId)
}
Isolated subagents
Child runs should have bounded scope, inspectable state, and a clear handoff back to the parent.
const child = await spawnSubagent({
session_id: session.id,
prompt: "investigate the lint failures",
execution: "background",
})
// later:
// waitTask(child.task_id)
// or react when completion is projected back into the parent session
Filesystem-backed artifacts
Big outputs should live on disk with stable references so they can be revisited later without bloating active context.
const artifact = await persistArtifact({
kind: "tool_output",
content: stdout,
})
appendEvent({
type: "artifact.created",
artifact_id: artifact.id,
path: artifact.path,
})
The kernel — loop, event log, tool runtime, background tasks, subagents, artifacts, compaction — is built. Per-feature design docs live in plans/.
These are the repos I've been reading against while trying to figure out what I actually want the core of leharness to be:
I want a harness core that is:
These were the main AI tools I used while doing the research and writing in this repo:
FAQs
Experimental agent harness CLI.
We found that leharness demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
/Application Security
A practical guide to securing GitHub Actions against supply chain attacks, covering malicious pull requests, credential theft, dependency risks, and release pipelines.
Security News
Composer 2.11 adds dependency cooldowns, joining package managers that delay new releases to reduce supply chain risks while allowing urgent security updates.
Threat Research
/Security News
Cursor removed a malicious Claude Code 2.1.313 extension from its marketplace. Socket examines registry records and the initial claims about its distribution.