HarnessOS

🧬 What is a Harness?

In AI, an LLM can think. A tool can act. But neither can persist, recover, coordinate, or remember on its own.

A Harness is the missing execution layer. It is the infrastructure that wraps around AI agents to give them:

• Persistence — Every task, every checkpoint, every event is written to a canonical SQLite store. If the agent dies, the work survives.
• Lifecycle — Tasks follow a strict state machine (pending → ready → in_progress → done/failed). Leases prevent two agents from claiming the same work. Stale leases are automatically recovered.
• Memory — Optional semantic memory powered by mem0 allows agents to recall context across sessions, threads, and even projects — without polluting the canonical state.
• Coordination — Dependency chains between tasks are resolved automatically. When task A completes, its dependents are promoted to ready. No human intervention needed.
• Portability — The harness is agent-agnostic and IDE-agnostic. It works with Copilot, Gemini, Cursor, Windsurf, or any custom runtime. Set it up once, use it everywhere.

Why does this matter?

Without a harness, every AI agent is a stateless function call. It forgets everything between sessions. It can't coordinate with other agents. It can't recover from crashes. It can't prove what it did or why.

HarnessOS turns disposable AI into a persistent, self-healing, auditable system.

Think of it this way:

• An LLM is a CPU.
• Tools are peripherals.
• HarnessOS is the operating system that makes them work together reliably.

🚀 Overview

HarnessOS provides the foundational execution framework for advanced autonomous agents. It focuses strictly on robust lifecycle management, leaving LLM inference and tool implementation to the consumer.

Latest release notes and breaking changes are tracked in CHANGELOG.md. The canonical hard-cut release checklist and fail-fast contract boundaries live in docs/release-playbooks.md.

Schema compatibility

• HarnessOS now enforces SQLite schema v5 as the only supported runtime store contract.
• Existing v2 databases are not migrated in place; opening them fails fast with an explicit recreate instruction.
• The runtime now persists blocked_reason on issues and milestones so dependency blockers are explicit, inspectable, and recomputed deterministically when queue state changes.
• The public package stays on the 2.x release line; schema, contract, and bundled-skill versions are tracked independently per surface so runtime cuts remain explicit without forcing a new package major every time one internal contract moves.

What it handles:

• Zod Plan Contracts — Strongly typed schema validation for robust planning.
• Session Contracts — Standardized agent execution lifecycles.
• Skill-Policy Registry — Dynamic management of agent capabilities and operational rules.
• Canonical SQLite Store — Robust, ACID-compliant state layer for leases, checkpoints, events, and task states.
• Session Orchestration — High-level inspection, queue promotion, and task lifecycle management.
• Symphony-style Agentic Orchestration — Fully agentic fan-out over ready issues, isolated worktree metadata/physical worktree adapters, gpt-5-high subagent routing, and deterministic evidence gates instead of human runtime checkpoints.

⚡ Key Features

🗄️ Canonical SQLite State

SQLite acts as the absolute source of truth for:

• Leases — Task-scoped locks to prevent concurrent race conditions.
• Checkpoints — Snapshot history of agent progress.
• Events — Immutable transaction logs.
• Task State — Workflow queues and resolutions.

📋 Batch-First Planning & Promotion

• harness_orchestrator(action: "plan_issues") accepts a canonical milestones[] batch only, even when importing a single milestone.
• create_campaign accepts an optional typed policy object with owner, serviceLevel, escalationRules, and dispatch, while plan_issues and the scheduler injector accept first-class workflow metadata on issues and milestones through deadlineAt, recipients, approvals, and externalRefs.
• Milestone hierarchy is preserved with depends_on_milestone_keys for in-batch edges and depends_on_milestone_ids for previously imported milestones.
• promote_queue advances work only when both issue-level and milestone-level dependencies are truly done.
• harness_inspector(action: "next_action") now returns a structured context block that points to the exact issue, milestone, blocker, lease, or policy escalation behind the recommendation, so queue decisions are auditable instead of heuristic black boxes.
• Campaign-level policy defaults still merge into issue-level overrides, and claim ordering now considers effective priority, policy breaches, issue deadlines, and the existing aging rules through one shared dispatch path.

🧠 Optional Memory Derivation

• Integrating mem0-mcp provides advanced semantic memory and context extraction.
• Lazy Loading — Derived memory is loaded only when needed to conserve resources.
• Failsafe Operations — If mem0-mcp is unavailable, the harness gracefully degrades without corrupting the canonical SQLite tasks.

🧭 Capability Discoverability

• harness_inspector(action: "capabilities") exposes the runtime tool surface, bundled skills, policy-driven skills, Symphony orchestration metadata, and mem0 state in an agent-readable format.
• The orchestration block advertises Symphony mode, the harness_symphony actions, the gpt-5-high default profile, four-agent fan-out defaults, required dispatch fields, worktree isolation responsibilities, Codex runner contracts, accepted evidence artifact kinds, and runtime metadata artifact kinds so hosts can discover support without hardcoded assumptions.
• The packaged skills under .github/skills mirror the canonical runtime contract, so prompts, docs, and MCP discovery stay aligned.
• The bundled skill manifest now publishes explicit workload profiles (coding, research, ops, sales, support, assistant) and per-skill workloadProfileIds, so hosts can specialize without hardcoding the core runtime to one domain.
• Human-facing discovery docs now live in one place per surface: docs/mcp-tools.md for MCP tools, docs/cli-reference.md for the installable CLIs, docs/workload-profiles.md for workload selection, and .github/skills/README.md for the bundled skill index.

🧩 Workload-Aware Skill Sync

• harness-setup now records a canonical selectedWorkloadProfile for every registered host under ~/.agent-harness/config.json.
• harness-sync installs only the skills required by that workload profile and prunes the rest atomically, instead of shipping one implicit all-skills pack to every host.
• assistant remains the explicit full-surface profile when a host must stay multi-domain; other profiles keep the runtime domain-agnostic while specializing guidance at the host edge.
• The repository now ships reference workspaces for assistant, research, ops, and support under examples/ so non-coding teams can start from concrete queues, workflow metadata, and handoff assets instead of coding-only scaffolds.

⏱️ Reusable Scheduler Injector

A cron-aware, idempotent injector for scheduled work (src/bin/scheduler-inject.ts), supporting full 5-field cron expressions to safely trigger work without duplications.

Agentic Symphony-Style Orchestration

• loadSymphonyWorkflow() resolves repo-owned WORKFLOW.md contracts with YAML front matter, typed defaults, $VAR path/secret resolution, strict prompt interpolation, and reload semantics that preserve the last known good workflow on invalid edits.
• createSymphonyPhysicalWorktree() and cleanupSymphonyPhysicalWorktree() let a host materialize an assigned worktree with safe refs, root containment, repo-owned hooks, timeouts, idempotent cleanup, and per-run evidence manifests/logs outside the removable checkout.
• launchCodexAppServerRunner() defines the opt-in Codex app-server runner boundary with fake-process coverage, bash -lc workflow command execution, runner/thread/turn identity, Symphony session-id derivation, read/turn timeout normalization, typed startup/turn error categories, and an additive startTurnWithTelemetry() envelope for event-capable transports with continuation recommendations, non-stall approval/user-input events, stall detection, token/rate-limit telemetry, and retry/backoff evidence.
• harness_symphony(action: "compile_plan") converts tracker-style milestones and slices into the canonical plan_issues batch without mutating state.
• harness_symphony(action: "dispatch_ready") assigns ready issues to one compatible subagent and one isolated worktree per issue, with gpt-5-high and four-agent fan-out as the discoverable defaults.
• harness_symphony(action: "inspect_state") reads leases, worktree artifacts, evidence references, recent events, and orchestration health flags.
• runOrchestrationSupervisorTick() executes one deterministic autonomous supervisor tick, while runOrchestrationSupervisor(), harness-supervisor, and harness_symphony(action: "supervisor_run") provide bounded autonomous polling with stop conditions and backoff.
• Completion remains no-human-checkpoint: the supervisor owns inspect/promote/dispatch and, in execute mode, requires an assignmentRunner command to run dispatched assignments and attach command-produced test, E2E, CSQR-lite, optional screenshot, state export, and codebase evidence before closing work.
• Copy/paste MCP payloads live in examples/orchestration-symphony/, and the runtime contract is documented in docs/orchestration-no-schema-v1.md.

Linear-Like Orchestration Dashboard

• A full Next.js dashboard lives in apps/dashboard and consumes the stable harness-os/orchestration dashboard view model.
• The app renders campaign metrics, ordered issue lanes, active leases, evidence summaries, CSQR-lite scorecards, recent events, and health flags without adding React/Next.js to the core package runtime dependencies.
• Run npm run dashboard:install, then start it with HARNESS_DASHBOARD_DB_PATH and HARNESS_DASHBOARD_PROJECT_ID to read a live HarnessOS SQLite database. Demo data is opt-in only via HARNESS_DASHBOARD_DEMO=1.
• Use npm run dashboard:verify after dashboard changes; it rebuilds the core package, installs app dependencies from lockfile, runs typecheck/tests, and executes next build.
• The operator runbook is documented in docs/orchestration-dashboard.md.

💻 Getting Started

1️⃣ Installation & Multi-Host Setup

npm install -g harness-os mem0-mcp

HarnessOS targets Node.js 22+ and ships with installable CLIs for runtime setup, scheduling, and MCP registration.

Register the lifecycle MCP server for Codex, Copilot CLI, and antigravity in one pass:

# Creates ~/.agent-harness/{harness.sqlite,mem0} if missing and configures the hosts
harness-install-mcp --host codex --host copilot --host antigravity

# Optional: bind a host to a specific workload profile
harness-install-mcp --host copilot --workload-profile research
harness-install-mcp --host codex --workload-profile ops
harness-install-mcp --host antigravity --workload-profile assistant

# Optional: inspect first without writing anything
harness-install-mcp --dry-run

You can still register extra host workspaces for skill sync:

harness-setup
harness-sync

harness-setup now persists a versioned host-sync config under ~/.agent-harness/config.json. If you still have the legacy flat {"hosts":["/path"]} shape, rerun harness-setup once to rewrite it before harness-sync. Each sync writes skills/bundle-manifest.json to the host and explicitly replaces outdated or drifted bundled skill assets instead of tolerating them indefinitely. The current host-sync schema is 3: each host now stores an explicit selectedWorkloadProfile, and sync records the installed workload-profile version plus checksum alongside the bundle metadata.

2️⃣ Reference workspaces by workload profile

See docs/workload-profiles.md for profile guidance, template pairing, and copy/paste quick starts.

2.1️⃣ Discovery reference

3️⃣ Environment Variables

4️⃣ Running Commands

# Run the cron-aware scheduler injector
harness-scheduler-inject

# Run the standard CLI session lifecycle
harness-session-lifecycle

# Start the MCP (Model Context Protocol) Server for lifecycle orchestration
harness-session-lifecycle-mcp

Generated public contract reference

Session lifecycle CLI payloads

Every payload must declare "contractVersion": "6.0.0".

Harness MCP tools

4️⃣ Planning Payloads

As of 2.0.0, queue planning is batch-first:

{
  "action": "plan_issues",
  "projectName": "Agent Harness Core",
  "campaignName": "Runtime hardening",
  "milestones": [
    {
      "milestone_key": "runtime-foundations",
      "description": "Agentic-first runtime improvements",
      "issues": [
        {
          "task": "Add capability introspection",
          "priority": "high",
          "size": "M",
          "deadlineAt": "2026-04-10T12:00:00.000Z",
          "recipients": [
            {
              "id": "platform-ops",
              "kind": "team",
              "label": "Platform Ops",
              "role": "approver"
            }
          ],
          "approvals": [
            {
              "id": "release-signoff",
              "label": "Release sign-off",
              "recipientIds": [
                "platform-ops"
              ],
              "state": "pending"
            }
          ],
          "externalRefs": [
            {
              "id": "runbook-capability-rollout",
              "kind": "runbook",
              "value": "ops://runbooks/capability-rollout",
              "label": "Capability rollout runbook"
            }
          ],
          "policy": {
            "escalationRules": [
              {
                "trigger": "deadline_breached",
                "action": "raise_priority",
                "priority": "critical"
              }
            ]
          }
        }
      ]
    },
    {
      "milestone_key": "runtime-polish",
      "description": "Follow-up polish",
      "depends_on_milestone_keys": [
        "runtime-foundations"
      ],
      "issues": [
        {
          "task": "Tighten tool discoverability prompts",
          "priority": "medium",
          "size": "S"
        }
      ]
    }
  ]
}

🧩 Architecture

For an in-depth look at how HarnessOS works, refer to the Architecture Documentation. The Symphony-style no-schema orchestration boundary is documented in docs/orchestration-no-schema-v1.md. Release highlights and migrations live in CHANGELOG.md.

The typical execution flow:

1. harness_orchestrator(action: "plan_issues") — Imports a canonical milestone batch into the queue.
2. runOrchestrationSupervisor(), harness-supervisor, or harness_symphony(action: "supervisor_run") — Runs bounded supervisor polling that promotes eligible work, fans visible ready issues out to isolated worktree/subagent assignments, and executes them when dispatch.assignmentRunner is supplied.
3. beginIncrementalSession() — Claims a ready task when single-worker execution is preferred instead of the supervisor fan-out path.
4. beginRecoverySession() — Resolves and overrides a stuck or failed task.
5. checkpoint() — Writes immediate progress to SQLite.
6. close() — Releases the lease and promotes newly eligible work.

🤝 Contributing

We welcome contributions to make HarnessOS even better! Please read our Contributing Guidelines to get started with setting up the project and submitting pull requests.

👨‍💻 Developer & Creator

📄 License

This project is licensed under the Business Source License 1.1 (BSL).

You may use this software for non-commercial and non-production purposes (e.g., development, testing, research, and personal projects) free of charge.

⚠️ Commercial and production use is strictly prohibited without prior written authorization.

On March 22, 2030, this license automatically converts to the Apache License, Version 2.0.