Skip to content

LocalHarness — architecture

The System

  1. 1
    you type into the terminal channel
  2. 2
    the orchestrator routes scores an agent card — live wiring is planned
  3. 3
    the agent loop reason → act → observe
  4. 4
    the context window built each turn, compacted at 80%
  5. 5
    the model completes locally — vLLM · llama.cpp · Ollama · LM Studio
  6. 6
    tools dispatch fenced — registry validates, pre/post hooks fire
  7. 7
    built-ins run and return a result for the loop to observe
  8. ↺
    the event bus every step lands here: typed, ordered, replayable
  9. ↺
    the memory slot the memory plugin adds recalled context each turn
fig. 01 — PLATE I — the shipped runtime: one request finding its way through

the parts

  • you a terminal or a chat app; every conversation comes in the same way.
  • the orchestrator one main agent reads your task and runs the loop: think, act, check, repeat.
  • tools read, write, run, search — an agent holds only the tools you allow.
  • the helpers specialists take delegated pieces, each in a fresh window, fenced to its job.
  • the model server the thinking runs on the server you already have — vLLM, llama.cpp, Ollama, LM Studio.
  • the bus every step is written down in order; the live view and the replay read it.
  • the plugins memory, chat, the phone app, pictures and autoresearch plug in — and each can be switched off.
_deeper src/localharness/ ↗SECURITY.md ↗_getting started ↗

The Loop

One turn at a time — read, act, check. Gates keep a run honest and stop it running away.

  1. 1
    task in a turn begins
  2. 2
    think the model
  3. 3
    act a tool call
  4. 4
    look the result — then loop back to think
  5. ↺
    budgets cap the work before each step
  6. ↺
    parse-repair fix a malformed tool call
  7. ↺
    act-guard did it actually act, before answering?
  8. ↺
    self-check review the answer before it ships
  9. ↺
    stuck-detector nudge once, then stop a run that spins
  10. ✓
    answer the turn ends
fig. 02 — one turn — and the gates that keep it honest

the gates

  • Budgets every run gets a ceiling on how many actions it may take and how long it may run, checked before each step.
  • Act-guard if the model announces a plan but then stalls without doing anything, the harness nudges it once to actually take the step.
  • Self-check before a plain answer goes out, the model is asked to review its own work and confirm it, or fix it.
  • Parse-repair when the model’s tool request comes out garbled, the harness repairs the format and retries instead of crashing.
  • Stuck-detector if it keeps repeating the same move without progress, the harness first nudges it, then stops the run rather than spin forever.
_deeper agent/loop.py ↗_demo ↗

The Plugins

how it composes

Core owns the loop, the tools, the config and the permissions — everything else is a plugin.

  • the manifest each plugin declares in code its name, kind, commands, settings and needs.
  • the lifecycle every session runs each plugin through the same steps, then stops them in reverse order.
  • the slots a plugin fills a port core already has — a tool, a channel, a command, or the one memory slot.
  • doctor each plugin brings its own health checks, and doctor runs them without starting anything.
  • the off switch any bundled plugin turns off with one setting, and its commands then say how to turn it back on.
  • the import rule core never imports a plugin, and a test fails if it does.

the bundled plugins

_deeper plugins/api.py ↗plugins/builtin.py ↗README — write a plugin ↗test_import_direction.py ↗examples/plugin-template/ ↗