leharness

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:

• the loop
• the event log
• the tool runtime
• the task model
• background vs blocking execution
• subagents
• compaction
• and the products that can grow on top of that core

Also, the name exists because I dreamt up the project while I was in Paris.

CLI

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 Ollama:

ollama pull gemma4:26b
lh --provider ollama

Useful options:

lh --session <id>        # resume an existing session
lh --provider openai     # choose openai or ollama
lh --model <name>        # override the provider's default model
lh --help                # print usage

Environment variables:

LEHARNESS_HOME=...             # override the session storage directory
LEHARNESS_PROVIDER=openai      # set the default provider
LEHARNESS_MODEL=gpt-4o-mini    # set the default model
OPENAI_API_KEY=...             # required for OpenAI
LEHARNESS_OLLAMA_BASE_URL=...  # override the Ollama OpenAI-compatible URL

Sessions are saved under .leharness/sessions in the current working directory unless LEHARNESS_HOME is set.

For local package development:

pnpm install
pnpm package:verify

Why

Most of the interesting agent repos mix together:

• a harness kernel
• product surfaces
• UI/TUI
• routing and integrations
• a lot of operational scar tissue

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.

High-Level Goals

• Build a small, explicit agent loop that stays easy to reason about.
• Use append-only event logs as the canonical session state.
• Persist important state and large outputs to the filesystem whenever possible.
• Treat long-running work as a first-class concept instead of a shell-only hack.
• Support isolated subagents and background work without turning the core into spaghetti.
• Keep the harness channel-agnostic so CLI, web, TUI, bots, or VM runners can all sit on top of the same engine.
• Make the system easy to revisit and improve in bursts instead of requiring rewrites every time a new feature appears.

Core Bets

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,
  })

MVP Shape

The first version should prove the kernel, not the product:

• CLI-first
• one provider
• append-only session log
• artifact persistence
• a few core tools
• one compaction path
• task handles for background-capable work
• isolated subagent execution
• synthetic completion notifications projected back into session state

If that part is solid, the rest should mostly be feature work instead of surgery.

What Can Grow On Top

Once the core is stable, these should be things I can add independently:

• web inspector
• richer CLI UX
• coding-agent wrapper
• TUI
• MCP integration
• skills
• more tools
• better compaction strategies
• steering/follow-up ingress queues
• branchable session history
• evals and replay tooling
• VM runners
• Telegram or other bot adapters
• more opinionated agent products built on top of the same harness

Direct Inspiration

These are the repos I've been reading against while trying to figure out what I actually want the core of leharness to be:

• OpenAI Codex for strong tool/runtime layering and task-oriented execution. Notes: research/codex-architecture.md
• Claude Code leak coverage because I ended up studying a research copy for prompt caching, long-running task behavior, and subagent patterns. Notes: research/claude-code-architecture.md
• OpenCode for durable session state, artifacts, and a TypeScript codebase that is easier to read than most. Notes: research/opencode-architecture.md
• OpenDev for the cleanest staged loop and the best "this code was built to be explained" architecture of the bunch. Notes: research/opendev-architecture.md
• OpenClaw mostly as an adjacent reference for what starts growing around a harness once it turns into more of an agent product. Notes: research/openclaw-architecture.md

North Star

I want a harness core that is:

• simple enough to explain
• modular enough to evolve
• durable enough to resume
• and strong enough that future work feels like adding a feature, not rebuilding the foundation

AI Tools Used

These were the main AI tools I used while doing the research and writing in this repo:

• OpenAI Codex
• Claude Code leak coverage

Links