harny

Harny

Harny is a local-first workflow runtime for auditable AI-assisted software development. Workflows are declarative YAML DAGs, can mix Claude and Codex, persist resumable state locally, and keep privileged effects such as commits and pull-request publication outside the agents.

Install

Requires Bun 1.3+ and Git.

bun add -g @lfnovo/harny
# or
bunx @lfnovo/harny "implement the requested feature"

Claude workflows use the Claude Agent SDK authentication. Codex nodes use the pinned official Codex SDK and the user's existing Codex authentication/config; a separately installed Codex executable is not required. GitHub PR delivery uses the installed gh CLI. Tokens never belong in workflow YAML or Harny's provider config.

Quick start

# Planner → sequential tasks → developer/validator retry → validated commits
harny "add JSON export to the CLI"

# Also push and create/update a draft GitHub PR
harny --workflow feature-pr "add JSON export to the CLI"

# Load an explicit workflow file
harny --workflow ./.harny/workflows/custom.yaml "run the custom workflow"

# Address review feedback on the current repository's existing PR
harny pr fix 123

Each normal run creates an isolated harny/<slug> branch and Git worktree. --isolation inline is available when isolation is not wanted.

New to agent harnesses? Start with the Harny documentation. It provides a progressive user path and a separate development path for contributors.

Runtime model

Workflow loading is:

YAML → schema validation → static validation → normalized DAG → scheduler

Named workflow precedence is:

<repo>/.harny/workflows > ~/.harny/workflows > bundled workflows

Markdown commands use the equivalent commands/ precedence. Validation occurs before worktree creation or provider cost and checks duplicate IDs, missing dependencies, cycles, output references, retry bounds, human timeouts, provider capabilities, and reachable outcomes.

The v1 scheduler is sequential and deterministic: one ready node runs at a time in declaration order. Supported node types are:

• agent — structured provider invocation with optional provider/model override and guards.
• command — argv-based subprocess; inline shell scripts and plugins are not workflow escape hatches.
• foreach — bounded, sequential steps per item, with persisted step checkpoints.
• human — interactive input or persistent async parking with mandatory timeout.
• commit — privileged commit of exactly the validated ChangeSet.
• pull_request — privileged, idempotent GitHub draft-PR delivery.
• cancel — finite terminal cancellation.

Bundled workflows:

• feature-dev — plan, implement, independently validate, commit each task, then validate the accumulated branch.
• feature-pr — feature-dev plus push and draft PR create/update.
• review-fix — internal definition used by harny pr fix <number> to address feedback on the current remote head.

Providers and safety

AgentProvider normalizes structured output, cwd, sessions, transcripts, usage, cancellation, transient errors, and capabilities. Claude is the default. A node can select Codex:

- id: planner
  type: agent
  command: planner
  provider: codex
  requires: [structured_output]

Unsupported capabilities fail before execution. In particular, the Codex SDK adapter advertises structured output, session resume, cwd, cancellation, and a read-only sandbox, but does not claim Harny's path-aware per-tool guards.

Logical provider connections can be declared globally in ~/.harny/providers.json. Project-local provider files are intentionally not loaded, so an untrusted repository cannot redirect agent traffic or choose credential variables:

{
  "version": 1,
  "providers": [
    {
      "id": "claude_proxy",
      "type": "claude",
      "base_url": "https://claude-compatible.example/v1",
      "api_key_env": "CLAUDE_PROXY_API_KEY",
      "model": "claude-compatible-model"
    },
    {
      "id": "codex_proxy",
      "type": "codex",
      "base_url": "https://openai-compatible.example/v1",
      "api_key_env": "CODEX_PROXY_API_KEY",
      "model": "gpt-compatible-model"
    }
  ]
}

Set the named environment variables outside the file, then use the logical ID as a workflow's provider. base_url, key-variable name, provider type, and default model are fingerprinted into persisted sessions; changing the connection prevents an unsafe resume. Secret values are neither persisted nor fingerprinted. The built-in claude and codex IDs remain available and can also be overridden in this global file.

Developer output is captured as a content-addressed ChangeSet. Validation checks that exact ChangeSet before and after the validator. The commit executor recalculates it, stages only registered paths, and fails if contents changed or an unexpected file appeared:

implemented diff = validated diff = committed diff