Heddle is an open-source terminal coding agent runtime and CLI for real project work.
It is designed for workflows where an agent needs to inspect a live repository, make bounded changes, verify results, keep continuity across sessions, and stay observable to the operator. Heddle supports OpenAI and Anthropic models, stores local workspace state under .heddle/, and includes both a terminal chat experience and a browser control plane.
In plain terms: Heddle is for people who want an agent that can work inside an actual project, not just answer isolated prompts.
Heddle is aimed at people who want more than a one-shot coding chat wrapper.
It is a good fit if you want:
- a terminal-first coding agent that works in a real repository
- local state and durable project memory
- explicit traces, approvals, and reviewable workflow artifacts
- a browser control plane for local oversight
- a path from interactive use to programmatic and scheduled agent workflows
Heddle is probably not the right fit if you only want a very simple one-shot prompt runner and do not care about sessions, persistence, observability, or operator control.
At a high level, Heddle helps with:
- understanding unfamiliar repositories
- making code or doc changes inside a real workspace
- running bounded verification like builds, tests, and repo review
- keeping multi-step work going across sessions instead of starting from scratch each time
- exposing more operator visibility than a black-box chat tool
If you want a terminal-first coding agent with local state, review traces, and a path toward longer-running workflows, that is the problem Heddle is trying to solve.
Heddle working in the terminal with live progress, tool activity, plans, and review output:
Heddle can inspect files, explain code, make edits, run shell commands with the right approval model, and carry a task through multiple turns.
Terminal chat/dev workflow showing file edits, inline diff output, and verification-oriented follow-through:
The local control plane gives you a browser-based view of the current workspace, saved sessions, heartbeat tasks, and recent activity:
Saved session review in the control plane, with conversation history in the center and review evidence on the right:
- Install Heddle:
npm install -g @roackb2/heddle- Set a provider API key:
export OPENAI_API_KEY=your_key_here
# or
export ANTHROPIC_API_KEY=your_key_here- Move into any repository you want to inspect:
cd /path/to/project- Start chat:
heddle- Try a prompt like:
Summarize this repository, show me the main build/test commands, and point out the likely entrypoints.
- If you want the browser oversight UI too:
heddle daemonThe main way to use Heddle is interactive chat in a repository:
heddleFrom there, Heddle can inspect files, explain code, make edits, run shell commands with the right approval model, and carry a task through multiple turns.
This is the core feature. If you only use Heddle as a coding agent in the terminal, this is the part you care about.
More: Chat and sessions guide
Heddle keeps saved sessions under .heddle/ so longer work does not have to reset every time. That means you can come back to an interrupted task, continue a previous debugging thread, or preserve project-specific context across runs.
This matters if you are doing real multi-step work rather than one-shot prompts.
Typical session commands include:
/session list/session switch <id>/continue/compact
More: Chat and sessions guide
The control plane is Heddle's local browser UI:
heddle daemonIt gives you a browser-based view into sessions, run state, heartbeat tasks, and review-oriented details. The purpose is operator oversight: seeing what the agent is doing, reviewing history more comfortably, and managing local runs from a UI instead of only from the terminal.
If terminal chat is the execution surface, the control plane is the oversight surface.
This is useful if you want a more inspectable and operator-friendly workflow than a plain CLI transcript.
More: Control plane guide
Heddle can keep durable project knowledge in markdown notes under .heddle/memory/.
The idea is simple: if the agent learns a stable fact about your repo — architecture notes, command quirks, recurring build issues, conventions — it can save that knowledge so future sessions do not have to rediscover it.
This is not meant to be a hidden vector database or magical long-term memory. It is readable, local, workspace-scoped memory that both the agent and the human can inspect.
This matters if you want the agent to become more useful over time in a specific project.
More: Knowledge persistence
Heartbeat is Heddle's model for bounded autonomous wake cycles.
Instead of only running when a human types a prompt, a heartbeat task lets Heddle wake up on a schedule, do a limited amount of work, checkpoint the result, and decide whether to continue, pause, complete, or escalate.
Example commands:
heddle heartbeat start --every 30m
heddle heartbeat task add --id repo-gardener --task "Check for safe maintenance work" --every 1h
heddle heartbeat task listWhy this exists: some agent work is not a single interactive chat. You may want periodic repo inspection, recurring maintenance checks, scheduled summaries, or a host that can resume work in bounded steps.
If you do not need scheduled or semi-autonomous workflows, you can ignore heartbeat entirely and just use chat.
More: Heartbeat guide
Semantic drift is optional telemetry that helps you see whether the assistant's responses appear to be moving away from the recent semantic trajectory of the conversation.
With optional CyberLoop integration installed, Heddle can surface drift levels such as:
drift=unknowndrift=lowdrift=mediumdrift=high
This is an observability feature, not a magic correctness guarantee. It is meant to help operators notice when a run may be getting less aligned with its recent direction.
If you are just looking for a coding agent, you do not need to care about this on day one. If you care about agent observability and runtime behavior, it is one of Heddle's more distinctive features.
More: Semantic drift
Heddle is not only a CLI. The npm package also exposes runtime primitives such as runAgentLoop and runAgentHeartbeat so other hosts can build on top of it.
This is for people building their own agent hosts, schedulers, or control surfaces rather than only using the packaged CLI.
More: Programmatic use
Global install:
npm install -g @roackb2/heddleRun without a global install:
npx @roackb2/heddleThe installed CLI command is heddle.
- Node.js 20+
- an API key for at least one supported provider:
OPENAI_API_KEYANTHROPIC_API_KEY
If you want semantic drift telemetry in chat, install cyberloop in the same environment as Heddle:
npm install -g cyberloop
# or for project-local usage
npm install cyberloopFor one-off usage without a global install:
npx -p @roackb2/heddle -p cyberloop heddleHeddle is already useful for real coding-agent workflows, but it is still evolving.
Current strengths include:
- terminal-first coding and repository workflows
- explicit traces, approvals, and local workspace state
- browser-based oversight through the control plane
- local-first heartbeat primitives for scheduled agent work
- practical programmatic hooks for custom hosts
Current limitations include:
- the browser control plane is still early compared with a full IDE-like environment
- some advanced workflows remain better documented in source and examples than in polished product UX
- the project surface is still changing as the runtime matures
If you want to work on Heddle itself:
git clone https://github.com/roackb2/heddle.git
cd heddle
yarn install
yarn build
yarn testSee Development and contributing for the fuller contributor workflow.
MIT