How thu-nmrc/openharness works
1. What this repository is
OpenHarness is not a product app; it is a runtime framework for autonomous agent work. The repo mainly contains control scripts, markdown contracts, and templates that govern how an agent behaves over long sessions inside an OpenClaw workspace.
2. Primary execution boundary
The framework assumes it runs inside ~/.openclaw/workspace/harness/{task-slug}/ and interacts heavily with the filesystem as the system of record. Most state is stored in Markdown files rather than a database or service API, which makes the workspace itself the durable runtime boundary.
3. Entry point and agent wiring
SKILL.md is the agent-facing entry point recognized by OpenClaw. The README positions this file as the trigger that equips the agent with harness behavior, while the scripts implement the runtime machinery behind that behavior.
4. Bootstrap and lifecycle control
scripts/harness_boot.py is the top-level startup controller. It checks existing state, handles stuck sessions, enforces a circuit breaker after repeated failures, and starts the session lifecycle before any task work proceeds.
5. Session state and cross-session memory
scripts/harness_heartbeat.py and scripts/harness_memory.py manage the persistent state model. The README describes a three-layer memory design:
- templates/heartbeat.md as a compact Layer 1 pointer index
- templates/knowledge/ as Layer 2 topic knowledge
- an append-only execution stream log as Layer 3
This is the main mechanism for resuming interrupted work and avoiding context-window blowup.
6. Task contract and work plan
templates/mission.md, templates/playbook.md, and templates/progress.md form the operational contract for the agent. mission.md defines what must be achieved, playbook.md defines the stepwise execution path, and progress.md records current work status and checkpoints. These documents constrain behavior and make the task auditable.
7. Validation boundary
scripts/harness_eval.py is the external judge. It consumes templates/eval_criteria.md and performs independent validation so the agent is not allowed to certify its own completion. Architecturally, this is a hard separation between work execution and completion approval.
8. Entropy control and cleanup
scripts/harness_cleanup.py is the maintenance layer. It trims logs, archives old records, and keeps the runtime environment from accumulating too much noise. This is a core part of the design because long-lived agent sessions are expected to grow continuously unless cleaned.
9. Scheduling and unattended operation
scripts/harness_setup_cron.py and templates/cron_config.md define the time-based trigger mechanism. The framework is designed for 24/7 unattended execution, so cron is the external scheduler that repeatedly re-enters the boot/evaluate/cleanup loop.
10. Parallelism and coordination
scripts/harness_coordinator.py introduces a file-system IPC model for multi-agent or multi-worker execution. The README describes coordinator-managed worker inbox/ and outbox/ directories, which means parallel tasks are dispatched and aggregated through files rather than a network service.
11. Offline consolidation and learning
scripts/harness_dream.py is a low-activity consolidation process. It scans accumulated execution history, distills recurring patterns, updates knowledge files, and feeds lessons back into playbook.md. This is the repo’s “background learning” path.
12. Architectural governance
scripts/harness_linter.py, references/architecture.md, and references/anti-patterns.md provide policy enforcement and design guidance. They define what the harness considers valid structure and what behaviors should be avoided, acting as the repository’s architectural guardrails.
13. How data moves through the system
The dominant flow is: bootstrap → read mission/heartbeat/playbook → execute steps → update progress/heartbeat → external validation → cleanup → wait for next scheduled run. A successful run may also feed knowledge back into the Layer 2/Layer 1 memory structures. The key architectural idea is that execution state is always externalized into files, not held only in agent context.
14. Repository composition
This repo is intentionally lightweight on code and heavy on orchestration artifacts. The scripts are the runtime engine; the templates are the durable contract/state format; the references are the policy layer; and the README/SKILL files explain how the agent should enter and operate within the harness.
Main entry points: harness_boot.py Bootstrap · harness_heartbeat.py Heartbeat · progress.md Progress · harness_memory.py Memory
Components 20
Entry & Runtime
Agent entrypoint and control scripts that drive execution.
State & Contracts
Filesystem-backed runtime state and operational markdown templates.
- Heartbeat · Persistent session pulse and pointer index used to resume long-running work.
scripts/harness_heartbeat.py - Memory · Manages durable layered memory and cross-session recall.
scripts/harness_memory.py - Mission · Defines the task objective and completion target.
templates/mission.md - Playbook · Stepwise operating plan that guides agent actions.
templates/playbook.md - Progress · Records current status, checkpoints, and work advancement.
templates/progress.md - Dream · Distills lessons from history and feeds them back into knowledge and playbooks.
scripts/harness_dream.py - Knowledge · Topic knowledge store for Layer 2 memory.
templates/knowledge/README.md - Memory Evolution · Utility for evolving stored memory and knowledge representations.
scripts/memory_evolution.py
Governance
Validation, scheduling, coordination, and architectural guardrails.
- Eval Criteria · Independent criteria used to judge completion.
templates/eval_criteria.md - Evaluator · Checks results against criteria without self-certification.
scripts/harness_eval.py - Cleanup · Trims logs and archives old records to control runtime entropy.
scripts/harness_cleanup.py - Cron Setup · Configures unattended re-entry into the harness loop.
scripts/harness_setup_cron.py - Cron Config · Template for time-based trigger configuration.
templates/cron_config.md - Coordinator · Dispatches work through filesystem inbox/outbox coordination.
scripts/harness_coordinator.py - Linter · Enforces repository structure and harness conventions.
scripts/harness_linter.py - Architecture · Documents the intended system structure and boundaries.
references/architecture.md - Anti-patterns · Documents invalid patterns and behaviors to avoid.
references/anti-patterns.md
Connections 25
- README → SKILL: introduces · README explains how the agent enters the harness through SKILL.md.
- SKILL → Bootstrap: activates · Agent entry routes into bootstrap control.
- Bootstrap → Mission: loads · Bootstrap reads the task objective before execution.
- Bootstrap → Heartbeat: restores · Bootstrap checks session state to resume or recover work.
- Bootstrap → Playbook: loads · Bootstrap uses the playbook as the execution path.
- Bootstrap → Progress: initializes · Bootstrap establishes current run status.
- Heartbeat → Memory: indexes · Heartbeat points into layered memory and execution history.
- Memory → Knowledge: stores · Memory manager maintains topic knowledge as durable state.
- Memory → Memory Evolution: evolves · Memory tooling updates and reshapes stored knowledge.
- Playbook → Progress: drives · Plan execution updates progress checkpoints.
- Progress → Heartbeat: persists · Run status is reflected back into session memory.
- Bootstrap → Coordinator: dispatches · Bootstrap can hand work to coordinated workers.
- Coordinator → Cleanup: returns · Distributed work still feeds maintenance and housekeeping.
- Coordinator → Progress: aggregates · Worker outcomes are merged into shared progress state.
- Evaluator → Eval Criteria: consumes · Evaluator applies the external completion criteria.
- Bootstrap → Evaluator: invokes · Bootstrap can trigger validation after work steps.
- Cleanup → Heartbeat: prunes · Cleanup removes old session noise while preserving live pointers.
- Cron Setup → Cron Config: configures · Scheduler setup is driven by the cron template.
- Cron Setup → Bootstrap: re-enters · Scheduled triggers cycle back into bootstrap.
- Dream → Knowledge: refines · Offline consolidation updates knowledge files.
- Dream → Playbook: feeds · Learned patterns are fed back into the playbook.
- Linter → Architecture: checks · Linter enforces documented architecture rules.
- Linter → Anti-patterns: guards · Linter helps prevent known anti-patterns.
- Evaluator → Cleanup: follows · Validation is followed by maintenance and entropy control.
- README → Architecture: describes · README frames the architecture and operating model.