harny

harny

The agentic-workflow execution platform — auto-evolving, explainable (auditable), with structured observation and automated improvement-proposal — built for teams that want to extract more value from their AI investments, especially with Claude Code.

The thesis: as AI does more of the implementation work, the human role splits into two — make decisions or evolve the workflow the AI uses. Iterating the dev pipeline itself becomes the dominant work of practically every dev. Harny is built to be the place where that work happens.

The mechanism: a planner → developer → validator discipline that catches bad output, structured observation of every run (state.json, transcripts, history, ML features), and a meta-loop that uses those observations to propose harder prompts, missing tooling, missing docs.

Quickstart

# Run feature-dev workflow against the current directory.
bunx @lfnovo/harny "build me a calculator CLI in calc.py"

# All runs in this directory + any registered cross-project assistants.
bunx @lfnovo/harny ls

# Visual viewer with run timeline, plan, sibling-branch warnings, Phoenix deep-links.
bunx @lfnovo/harny ui

harny requires Bun >= 1.3. The first bunx invocation installs the package; subsequent ones run instantly. For frequent use:

bun add -g @lfnovo/harny
harny "<prompt>"

How it works

A run goes through three phases by default (feature-dev workflow):

1. Planner reads the prompt, explores the codebase, emits a structured plan (plan.json).
2. Developer picks up the next pending task, makes code changes in a git worktree.
3. Validator runs read-only against the uncommitted tree, returns pass/fail with evidence.

On pass, harny composes the commit message and commits. On fail, the developer's session resumes with the validator's feedback. After N failed retries, the tree is reset and a fresh developer session starts. Every step is captured in <cwd>/.harny/<slug>/state.json — single source of truth, atomic writes, inspectable any time.

Other built-in workflows:

bunx @lfnovo/harny --workflow docs --input intent.json "document the CLI"
bunx @lfnovo/harny --workflow issue-triage --input issue.json "triage this issue"
bunx @lfnovo/harny --workflow feature-dev-engine "build me X"   # XState-based engine workflow (v0.2.0 preview)

Architecture

A quick map of the moving parts. Solid arrows are control flow; dotted arrows are data / observation.

flowchart TB
    User(("User / Claude Code"))

    subgraph CLI["harny CLI"]
        Runner["runner.ts<br/>parse args + subcommands<br/>(ls · show · answer · ui · clean)"]
    end

    subgraph Core["Core harness"]
        Orch["orchestrator.ts<br/>git worktree · branch · state init<br/>lifecycle: dispatch · recover · exit"]
        Engine["engine runtime<br/>runEngineWorkflow<br/>XState createActor + subscribe"]
        Machine[["Workflow Machine (XState)<br/>feature-dev · auto · echoCommit · custom"]]
        Dispatchers[["Dispatchers<br/>agentActor · commandActor<br/>humanReviewActor · commitActor"]]
    end

    subgraph Ext["External effects"]
        SDK["Claude Agent SDK<br/>runPhase → structured output"]
        Git[("git worktree / branch / commit")]
    end

    subgraph Persist[".harny/&lt;slug&gt;/"]
        StateFile[("state.json<br/>single source of truth")]
        PlanFile[("plan.json<br/>feature-dev only")]
    end

    subgraph Obs["Observation"]
        Viewer["Viewer UI<br/>harny ui"]
        Phoenix["Phoenix traces<br/>opt-in (HARNY_PHOENIX_URL)"]
    end

    User --> Runner
    Runner --> Orch
    Runner --> Viewer
    Orch --> Engine
    Engine --> Machine
    Machine --> Dispatchers
    Dispatchers -- "agentActor" --> SDK
    Dispatchers -- "commitActor · commandActor" --> Git
    Orch --> Git
    Orch -. init .-> StateFile
    Machine -. "phases[] · history[]" .-> StateFile
    Machine -. write .-> PlanFile
    Viewer -. read .-> StateFile
    Viewer -. read .-> PlanFile
    Orch -. withRunSpan .-> Phoenix
    Dispatchers -. "phase spans" .-> Phoenix

Reading the diagram: