harness-os — HarnessOS (giulio-leone/harness-os)

HarnessOS is a TypeScript/npm-based execution framework described as "The operating system for autonomous AI agents." It provides a canonical SQLite state layer with strict ACID guarantees for task lifecycle management (pending → ready → in_progress → done/failed), lease-based concurrent access control, and Symphony-style orchestration for parallel agent fan-out. The framework ships as an npm package (harness-os), an installable CLI (harness-setup + harness-sync), and a set of bundled skills in .github/skills/. Key engineering choices: Zod plan contracts for typed schema validation, mem0 optional semantic memory integration, workload profile selection (coding/research/ops/sales/support/assistant), and WORKFLOW.md-based agentic orchestration with physical git worktrees per run. The harness_symphony orchestration mode supports four-agent fan-out with gpt-5-high subagent routing.

Compared to the seeds, HarnessOS is closest to claude-flow (Archetype 3 — MCP-anchored toolserver) in its SQLite state layer and multi-agent orchestration. The key delta is the workload profile selection system, Zod contract validation, and Symphony-style WORKFLOW.md orchestration rather than claude-flow's hive-mind consensus protocols.

Overview — HarnessOS (giulio-leone/harness-os)

Origin

HarnessOS (BUSL-1.1 license) is maintained by Giulio Leone. Published on npm as harness-os. Tagline: "Harness is all you need."

Philosophy

From README:

"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."

Core Tenets

1. Persistence: Every task, checkpoint, event written to canonical SQLite. Agent death doesn't lose work.
2. Lifecycle: Tasks follow strict state machine (pending → ready → in_progress → done/failed). Leases prevent concurrent claim of same work.
3. Memory: Optional semantic memory via mem0 for cross-session context.
4. Coordination: Dependency chains between tasks resolved automatically.
5. Portability: Agent-agnostic and IDE-agnostic (Copilot, Gemini, Cursor, Windsurf).

Workload Profiles

The framework specializes behavior per domain via workload profile selection:

• coding — software engineering workflows
• research — research and analysis
• ops — operations and infrastructure
• sales — sales and outreach
• support — customer support
• assistant — full-surface multi-domain (default)

Architecture — HarnessOS (giulio-leone/harness-os)

Distribution

• Type: npm package
• Install: npm install harness-os (or harness-setup CLI)
• CLI:
  • harness-setup — configures workload profile, registers host, creates ~/.agent-harness/config.json
  • harness-sync — installs skills for selected workload profile, prunes irrelevant skills

Directory Structure

harness-os/
├── src/
│   ├── bin/
│   │   └── scheduler-inject.ts    # Cron-aware idempotent scheduler
│   └── (core framework source)
├── harness-rs/                    # Rust components
├── apps/                          # Application packages
├── .github/
│   └── skills/                    # Bundled skill index
├── docs/
│   ├── mcp-tools.md               # MCP tools reference
│   ├── cli-reference.md           # CLI reference
│   ├── workload-profiles.md       # Workload selection guide
│   └── ...
├── examples/                      # Workspaces for assistant/research/ops/support
└── package.json

SQLite Schema (v5 — enforced)

• Schema v5 is the ONLY supported runtime store contract
• v2 databases fail fast with explicit recreate instruction
• Stores: leases, checkpoints, events, task states, queue metadata

Required Runtime

• Node.js
• SQLite (canonical state)
• mem0-mcp (optional semantic memory)
• Any AI agent runtime (Copilot, Cursor, Windsurf, Gemini, etc.)

Target AI Tools

Explicitly agent-agnostic: Copilot, Gemini, Cursor, Windsurf, and any custom runtime. Cross-tool portability is a design goal.

Components — HarnessOS (giulio-leone/harness-os)

MCP Tools

harness_orchestrator

• plan_issues — canonical milestones batch import; milestone hierarchy with depends_on_milestone_keys
• create_campaign — create campaign with typed policy (owner, serviceLevel, escalationRules, dispatch)
• promote_queue — advance work when both issue-level and milestone-level dependencies are done

harness_inspector

• next_action — returns structured context block pointing to exact issue/milestone/blocker/lease behind recommendation
• capabilities — exposes runtime tool surface, bundled skills, Symphony metadata, mem0 state

harness_symphony

• loadSymphonyWorkflow() — resolves WORKFLOW.md contracts with YAML front matter, $VAR resolution, strict prompt interpolation
• createSymphonyPhysicalWorktree() / cleanupSymphonyPhysicalWorktree() — worktree lifecycle with safe refs, root containment, repo-owned hooks, evidence manifests
• launchCodexAppServerRunner() — Codex app-server runner with startup/turn error categories, telemetry, stall detection, retry/backoff evidence

CLI Tools

• harness-setup — workload profile selection, host registration, ~/.agent-harness/config.json
• harness-sync — workload-aware skill installation and pruning
• scheduler-inject.ts — cron-aware idempotent scheduled work injector (full 5-field cron expressions)

Skills (.github/skills/)

Bundled skills per workload profile. Exact names not enumerated in public README but skill manifest publishes workload profiles: coding, research, ops, sales, support, assistant.

State / Memory

• Canonical SQLite store: leases, checkpoints, events, task states
• Optional mem0-mcp: semantic memory with lazy loading; failsafe degradation if unavailable
• Config file: ~/.agent-harness/config.json — selected workload profile per host

Uniqueness — HarnessOS (giulio-leone/harness-os)

Differs From Seeds

HarnessOS is closest to claude-flow (Archetype 3 — MCP-anchored toolserver) in its SQLite state layer, multi-agent orchestration, and npm distribution. The key deltas: (1) workload profile system — codified domain specialization (coding/research/ops/sales/support/assistant) with workload-aware skill sync is unique in the corpus; (2) Zod contract validation — strongly-typed schema validation for all plans, not just prompt-level instructions; (3) Symphony WORKFLOW.md contracts — YAML-front-matter workflow definitions loaded by the orchestrator, with $VAR resolution and reload-on-edit semantics; (4) harness_inspector auditable context — next_action returns a structured context block pointing to the exact SQLite record driving the queue decision, making queue behavior inspectable; (5) BUSL-1.1 license (not MIT/Apache) — indicates commercial intent.

Positioning

HarnessOS occupies a "persistence + orchestration infrastructure" niche — it is not a behavioral framework (no Iron Laws, no governance) but rather the execution substrate that makes agent work durable, recoverable, and auditable. The workload profile system is its most distinctive contribution: the idea that an "agent OS" should specialize differently for engineering vs operations vs sales workflows.

Observable Failure Modes

1. BUSL-1.1 license: Not fully open-source — Business Source License restricts commercial use; adoption in production systems requires legal review
2. Low stars (3): Despite sophisticated architecture, minimal community adoption
3. gpt-5-high routing: Symphony mode is documented with gpt-5-high profile — ties multi-agent orchestration to a specific OpenAI model naming convention
4. Schema v5 hard cut: v2 databases fail fast; no migration path means upgrading breaks existing deployments