Heddle

Your local AI dev team, controlled from the browser.

Heddle is a local control plane for Claude Code, Codex, MCP tools, and repository workflows.

It starts from a simple idea: keep your existing coding agents local, then give them a browser workspace, a team structure, scoped worker sessions, and a traceable delegation layer.

Start Heddle locally
  -> choose a YAML flow
  -> Heddle injects run-scoped MCP delegation tools
  -> your host Claude Code or Codex session leads the work
  -> isolated Heddle workers handle delegated tasks
  -> Studio shows reports, events, and run history

Heddle is not a cloud runtime and it is not a blank node-graph builder. The current implementation is a local recursive agent harness with a Studio UI and MCP-first delegation.

Important

This repository moves quickly. This README describes the current master branch and avoids claims that are not represented in the TypeScript schema or runtime. The product direction lives in docs/LOCAL_AGENT_CONTROL_PLANE.md, and the code-backed status checklist lives in docs/CURRENT_STATE.md.

What Heddle Gives You

Surface	What it does
heddle	Starts a host leader session from a selected flow and injects Heddle MCP delegation tools.
heddle mcp	Runs the stdio MCP bridge that exposes child-agent delegation tools.
heddle-subagent	Internal child-agent launcher behind MCP delegation.
Studio	Browser UI for editing flows, roles, hooks, skills, and watching runs.
Server	Local Fastify API for flow CRUD, run history, events, discovery, and SSE.
YAML flows	Source-controlled agent teams with host leaders and isolated workers.

Why It Exists

Most coding-agent setups hit the same wall:

• Claude Code and Codex are useful, but they live as separate local sessions.
• MCP servers, hooks, roles, and repo conventions are scattered across config files.
• Delegation is usually prompt text, shell copy-paste, or invisible sub-sessions.
• Browser UX is convenient, but developers still want code execution to stay local.

Heddle stitches those pieces into one local workspace:

• Host leader session: your normal local Claude Code or Codex profile.
• Heddle overlay: flow instructions, child-agent list, delegation rules, and reporting protocol.
• MCP delegation: typed tools such as heddle_delegate_reviewer and heddle_delegate_many.
• Isolated workers: scoped HOME/config, scoped resources, mandatory REPORT output.
• Trace layer: events and reports persisted under .heddle/traces.db.

Runtime Model

flowchart LR
  Studio["Heddle Studio<br/>browser control panel"]
  Server["Local Heddle Server<br/>flows, runs, events"]
  Leader["Host Leader Session<br/>Claude Code or Codex"]
  MCP["Heddle MCP Bridge<br/>delegate / status / report / cancel"]
  Workers["Heddle-managed Workers<br/>isolated Claude/Codex sessions"]
  Repo["Local repository<br/>your files stay local"]
  Trace[".heddle/traces.db<br/>events and reports"]

  Studio <--> Server
  Server --> Leader
  Leader --> MCP
  MCP --> Workers
  Workers --> Repo
  Workers --> Trace
  Server <--> Trace

Loading

The split is intentional:

Leader comes from your local provider.
Workers are managed by Heddle.
MCP connects them with a traceable delegation boundary.

Current Highlights

• Recursive agent-tree flow schema with claude-code and codex agent types.
• Host/isolated runtime metadata with MCP-only delegation transport.
• Provider profile discovery for local Claude Code and Codex installs.
• Run-scoped MCP config injection for host leader sessions.
• Dynamic MCP tools for enabled direct children, including heddle_delegate_<agent>.
• heddle_delegate_many for parallel worker dispatch from a single tool call.
• SQLite-backed run and event persistence under .heddle/traces.db.
• Studio UI for flows, roles, hooks, skills, resources, and run detail views.
• Default leader-workers flow with implementers, analysts, reviewer, fixer, debaters, synthesizer, and user-advocate.
• Phase-gated workflow policy: phase work can require user-advocate PASS before moving forward.
• Debate routing policy: casual debate, vs, comparison, recommendation, or decision prompts can route through debater agents.

Install

Install the CLI globally, then start Heddle from any repository:

npm i -g @aproto9787/heddle
heddle

Requirements:

• Node.js >=22.13.0
• Local Claude Code and/or Codex if you want real provider-backed runs

Heddle scans the current directory and packaged example flows, lets you choose a YAML flow, then launches the selected host leader with run-scoped MCP delegation tools.

Develop From Source

Use the source checkout for Studio and server development:

pnpm install
pnpm -r build

Run the local server and Studio:

pnpm --filter @heddle/server dev
pnpm --filter @heddle/studio dev

Defaults:

• Server: http://localhost:8787
• Studio: http://localhost:5173

Or start all dev processes through the workspace script:

pnpm dev

Run a Flow

From the published CLI:

heddle

From a built checkout:

pnpm --filter @aproto9787/heddle build
node packages/cli/dist/index.js

The CLI scans the current directory and examples/ for .yaml flows, lets you pick one, then launches the selected flow's root leader.

Headless run:

node packages/cli/dist/index.js \
  --flow examples/leader-workers.yaml \
  --prompt "Review this workspace and delegate as needed." \
  --headless

Start only the MCP bridge:

node packages/cli/dist/index.js mcp

The MCP bridge is normally launched by a host leader through a temporary run-scoped config generated by heddle.

Example Flow

version: "1"
name: Review Flow
repo: .

orchestrator:
  name: leader
  type: codex
  runtime:
    mode: host
    profile: codex-default
    applyResources: prompt-only
    delegationTransport: mcp
  system: |
    Plan the work, delegate concrete tasks, read child reports, and make the
    final decision.
  delegation:
    - to: reviewer
      when: Code or documentation needs a second pass.
  agents:
    - name: reviewer
      type: codex
      role: code-reviewer
      runtime:
        mode: isolated
        profile: codex-default
        applyResources: scoped-home
      system: |
        Review the assigned work and report concrete findings.

The active example set is under examples/. The default Studio/server path centers on examples/leader-workers.yaml.

Studio

Studio is a browser control surface for the local server:

• inspect and edit recursive flow trees
• configure agent roles, models, prompts, MCPs, hooks, and skills
• run selected flows against the local workspace
• stream run events and inspect worker reports
• keep YAML as the source of truth for Git review

Studio is intentionally a control panel over local execution. It does not move repository execution into a remote cloud runtime.

Resource Model

Heddle has three source-controlled workspace resource directories:

roles/*.yaml
hooks/*.yaml
skills/*.yaml

Resource behavior today:

• Roles provide defaults for type, model, system prompt, effort, description, and MCPs.
• Skills append prompt text.
• Hooks run local shell commands through the server runner.
• MCP names are resolved from user/workspace MCP config and written into temporary scoped config for a run.
• Host leaders use prompt-only flow overlays.
• Workers can receive scoped resources inside isolated HOME/config directories.

Repository Map

heddle/
├── apps/
│   ├── server/       Fastify API, flow validation, local CLI runs, traces
│   └── studio/       React + Vite browser control panel
├── packages/
│   ├── core/         Zod schemas and shared flow/run types
│   ├── cli/          heddle and heddle-subagent binaries
│   ├── mcp/          stdio MCP delegation bridge
│   └── runtime/      flow loading, resources, prompts, hooks, reports
├── examples/         YAML flows shown by server and Studio
├── roles/            reusable role definitions
├── hooks/            local hook definitions
├── skills/           prompt skill definitions
└── docs/             architecture, current state, implementation notes

API Surface

The local server exposes routes for:

• health: GET /health
• flows: GET /flows, GET /flows/get, PUT /flows/save, POST /flows/new, POST /flows/duplicate, DELETE /flows/:path
• runs: POST /runs, GET /runs, GET /runs/:id, POST /runs/:id/abort
• events: POST /runs/register, POST /runs/:id/events, GET /runs/:id/events, GET /runs/:id/stream, PATCH /runs/:id/status
• resources: GET /roles, GET /hooks, GET /skills, plus save/delete endpoints
• discovery: GET /mcps, GET /discover

Flow paths accepted by server run/save/get routes must stay under examples/ and end in .yaml.

What Heddle Is Not Yet

These are not implemented as shipped runtime guarantees today:

• visual DAG execution with typed edges
• routers, loop/join nodes, or graph-cost meters
• automated golden-path coverage for full leader-to-worker recursion
• cloud-hosted code execution

If you need the current baseline before changing docs, read docs/CURRENT_STATE.md.

Safety Notes

Warning

Heddle can run local CLI tools and shell hooks. Treat flows, roles, hooks, skills, and MCP configs as trusted code/configuration.

Current code paths include powerful execution modes:

• Claude Code adapter uses --permission-mode bypassPermissions.
• Codex adapter uses --dangerously-bypass-approvals-and-sandbox.
• CLI launch uses dangerous permission/sandbox bypass flags for root agents.
• Hooks run shell commands through child_process.exec.

Use Heddle only inside repositories and workspaces you trust.

Docs

• docs/LOCAL_AGENT_CONTROL_PLANE.md: target product and runtime contract
• docs/CURRENT_STATE.md: code-backed implementation status
• docs/ARCHITECTURE.md: system architecture
• docs/PROGRESS.md: project history and progress notes

License

Copyright (C) 2026 aproto9787

Heddle is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3.

Heddle is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for the full terms.