Heddle

Heddle is an open-source AI coding agent runtime and terminal-first workspace for real project work.

Official website: heddleagent.com

Terminal UI v2 is now the default. Run heddle or heddle chat to try the API-backed terminal experience. Messages, run events, and agent response streams now flow through the shared control-plane path, so terminal, browser, and mobile clients can follow the same work at the same time for smoother cross-device workflows. If you need the old terminal UI while the transition settles, run heddle chat-v1.

See Heddle In Action

Terminal, browser, and mobile surfaces can observe the same live session at once:

Review and approve sensitive actions from the control plane while the agent run stays visible:

Inspect workspace diffs from browser and mobile while the same conversation continues:

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/, includes both a terminal chat experience and a browser control plane, learns durable workspace knowledge while it works, and gives users a review path for file diffs, commands, approvals, and traces.

In plain terms: Heddle is for people who want an AI coding assistant that can work inside actual projects, learn each project's operating knowledge over time, switch between local workspaces, and remain inspectable instead of acting like a black box.

Why Try Heddle

Heddle is aimed at people who want more than a one-shot coding chat wrapper or stateless AI code assistant.

It is a good fit if you want:

• a terminal-first coding agent that works in a real repository
• an agent that learns durable project knowledge while working with you, using inspectable local memory
• explicit traces, approvals, and reviewable workflow artifacts
• a browser control plane for local oversight, workspace switching, and session review
• 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.

What Heddle Does

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
• switching between local workspaces from the browser control plane
• learning durable facts, preferences, and workflows from real usage
• exposing more operator visibility than a black-box chat tool

If you want a terminal-first coding agent with local state, review traces, workspace memory, and a path toward longer-running workflows, that is the problem Heddle is trying to solve.

Programmatic Use Layers

Heddle currently has two main programmatic layers:

• createConversationEngine: an alpha API for persisted multi-turn sessions with session storage, compaction, approvals, traces, semantic activity, and custom frontends or local hosts
• AgentLoopRuntimeService.run(...): a lower-level single-run execution loop for hosts that do not need persisted chat or session behavior

Advanced hosts can also reuse lower-level class APIs such as ToolRegistry, ToolExecutionService, TraceRecorder, TraceConsoleFormatter, and ReviewDiffParser when they intentionally assemble custom runtime or review surfaces.

If you want the programmatic surface, start with the Programmatic use guide.

For contributors, the compact architecture map lives in Core Layering and Chat Layering.

See Heddle

Terminal coding workflow

Heddle working in the terminal with live progress, tool activity, plans, and review output:

Heddle can inspect files, search with ignore-aware fallbacks, explain code, make edits, run shell commands with the right approval model, and carry a task through multiple turns. Terminal chat keeps long-running turns visible with tool activity, dim Thinking: progress text, real-time assistant markdown, and clearer approval prompts for repeated commands or searches.

Terminal change review

Terminal chat/dev workflow showing file edits, inline diff output, and verification-oriented follow-through:

Browser control plane overview

The default local control plane is the web-v2 browser client served by heddle daemon. It is the oversight surface for coding sessions, workspace state, current changes, heartbeat tasks, and settings:

The web-v2 client includes:

• Sessions: saved conversations, live assistant streaming, tool progress, approvals, and current workspace diff review.
• Composer controls: model and reasoning settings, semantic drift controls, @file mentions, and image attachments saved as local paths for view_image.
• Workspace switching: sidebar workspace selection plus Settings > Workspace for registering, renaming, and switching local projects.
• Tasks: heartbeat task creation, edit, enable/disable, run, resume, delete, live run state, and saved run records.
• Settings: language preferences, workspace management, and memory status with catalog health, note counts, pending candidates, and latest maintenance run.
• Mobile: focused panels for session list, conversation workbench, task detail, settings, and diff review.

The task workbench covers recurring heartbeat tasks, live run state, and run result review:

The same control plane supports mobile layouts, with the session list, workbench, and diff preview exposed as focused panels:

2-Minute Try-It Path

1. Install Heddle:

npm install -g @roackb2/heddle

2. Configure provider access.

For OpenAI, you can either sign in with your own ChatGPT/Codex account:

heddle auth login openai

Or use a Platform API key:

export OPENAI_API_KEY=your_key_here

If you keep both a stored OpenAI OAuth credential and an API key around for testing, you can explicitly prefer the API key for a run:

heddle --prefer-api-key
heddle --prefer-api-key ask "Summarize this repository"
heddle --prefer-api-key daemon

For Anthropic, use an API key:

export ANTHROPIC_API_KEY=your_key_here

OpenAI account sign-in is an experimental, user-selected transport for Heddle. It is not official OpenAI support, and Heddle is not affiliated with, endorsed by, or sponsored by OpenAI. Use of OpenAI services remains subject to OpenAI's terms and policies.

3. Move into any repository you want to inspect:

cd /path/to/project

4. Start chat:

heddle

5. Try a prompt like:

Summarize this repository, show me the main build/test commands, and point out the likely entrypoints.

6. If you want the browser oversight UI too:

heddle daemon

Open the browser control plane from the daemon output. From there you can use Sessions, Tasks, and Settings to inspect the active workspace, continue saved sessions, review changes, inspect memory status, and switch to another local project.

If you prefer a one-shot CLI run instead of interactive chat, use:

heddle ask "Summarize this repository"

ask still exits after one prompt, but it now records the run as a one-off saved session under .heddle/ so traces, memory maintenance, and later inspection use the same persisted conversation path as normal sessions.

The terminal chat footer and the control-plane session composer both show the active auth source for the selected model, so you can tell whether a session is using OpenAI account sign-in, API-key mode, or missing credentials.

Try The Learning Loop

Heddle gets more useful when it learns a reusable preference and applies it later. In chat, teach it a ticket format:

Whenever I ask you to create a ticket, use these sections: problem statement, proposed approach, considered alternatives, conclusion.

Then start a fresh session and ask:

Create a ticket for maintaining doc consistency after feature updates.

Heddle should recover the preference from its local memory catalog and produce the ticket in that structure. You can inspect what it learned with:

heddle memory status
heddle memory list
heddle memory search ticket

Major Features

Terminal chat for real coding work

The main way to use Heddle is interactive chat in a repository:

heddle

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

The terminal composer supports multiline prompts, prompt undo/redo, prompt history navigation, model picking with /model set, and reasoning-effort picking with /reasoning set. During a run, Heddle streams visible activity so you can see whether it is thinking, searching, calling tools, updating a plan, or waiting for approval.

More: Chat and sessions guide

Terminal UI v2 is the default

The default terminal chat is now the API-backed cli-v2 experience. Run heddle or heddle chat from a project to start it. The legacy terminal UI remains available as an explicit fallback through heddle chat-v1 while the transition settles.

The v2 terminal UI consumes the same local control-plane API as the browser UI and does not reach directly into core services. For users, the goal is one behavior model across interfaces. A saved conversation, selected model, reasoning setting, approval state, and live run status should be the same whether you are looking from the terminal, the browser control plane, or another device connected to the same local control-plane server. Messages, tool events, approval waits, and streamed agent responses are delivered through the shared session event path, so multiple devices can observe and continue the same work simultaneously instead of waiting for one surface to finish or refresh.

For contributors, the goal is a cleaner implementation path: TUI-specific rendering and keyboard behavior stay in cli-v2, shared semantics stay in core and server-owned control-plane APIs, and future advanced features can build on a maintainable API-first foundation instead of duplicating command/session logic in each interface.

Project instructions

Heddle can load a short project instruction file at startup so a fresh session starts with the repository's operating context. By default it loads the first non-empty file found in this order: HEDDLE.md, AGENTS.md, CLAUDE.md.

Only one default file is loaded to preserve context space. If a project needs a different path or intentionally wants multiple files, set agentContextPaths in heddle.config.json.

More: Project config

Sessions and continuity

Heddle keeps saved sessions under .heddle/ so longer work does not have to reset every time. Current versions store the session catalog at .heddle/chat-sessions.catalog.json and per-session bodies under .heddle/chat-sessions/. 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
• /model set
• /reasoning set

More: Chat and sessions guide

Knowledge Persistence: Heddle Learns While It Works

Heddle can learn durable project knowledge while it works with you.

When the agent notices reusable information — a preferred ticket format, a canonical verification command, an operational convention, a recurring repo quirk, or a stable workflow pattern — it can record a memory candidate and let a dedicated maintainer path fold that knowledge into cataloged markdown notes under .heddle/memory/.

The goal is practical recall: future sessions should know where to look instead of rediscovering the same context from scratch. Heddle does this through explicit catalogs, readable local notes, maintenance logs, and memory visibility commands rather than opaque retrieval.

The learning loop is intentionally concrete:

• notices durable facts and preferences during normal work
• records memory candidates without interrupting the user
• folds candidates into cataloged markdown through a maintainer path
• lets future sessions recover context through explicit discovery paths
• lets users audit memory with heddle memory status/list/read/search/validate

Try it on a real project: tell Heddle a durable preference or let it discover a stable workflow detail, then start a fresh session and watch it recover that context through the memory catalog.

For example, tell Heddle your preferred ticket template once, then ask for a ticket in a new session. The point is not just storing a note; it is making future work start from the operating knowledge you already taught the agent.

More: Knowledge persistence

Control plane and workspaces

The control plane is Heddle's local browser UI:

heddle daemon

It gives you a browser-based view into workspaces, sessions, run state, heartbeat tasks, memory health, 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.

The workspace switcher and Settings > Workspace page let you register local projects, switch the control plane between them, rename workspace entries, and pick a project folder from the browser UI. Heddle also keeps a user-level workspace registry so projects you have opened from the CLI or daemon can be rediscovered later.

The Sessions section supports a coding-review flow built around current work first. Review starts from the live Git working tree for the active workspace, with changed files, structured read-only diffs, and a larger full-diff viewer when the side panel is too tight. Historical turn diffs, review commands, verification commands, approvals, and trace events are still available, but they are separated from current review so old evidence does not distract from the task at hand.

Session chat in the control plane renders assistant markdown, receives per-session live updates for assistant streaming, tool progress, approvals, and saved-session refreshes, and keeps model/reasoning controls aligned with the terminal workflow. The session composer also includes drift controls, @file mention suggestions, and image upload controls for attaching local screenshots or reference images to a prompt.

The task surface has also moved beyond passive visibility: operators can create, edit, enable, disable, run, resume, and delete heartbeat tasks, inspect live run state, and review saved run records from the browser. Settings now include workspace and memory status views, so memory catalog health and maintenance history are visible without dropping back to terminal commands.

This is useful if you want a more inspectable and operator-friendly workflow than a plain CLI transcript. The layout adapts for phone use as well, with mobile-native navigation for Sessions, Tasks, and Settings, plus focused Chat/Review and task-run workflows.

More: Control plane guide

Runtime host model

Heddle is local-first, but it still has a runtime ownership model.

The short version is:

• Heddle uses one local control-plane server path for interactive chat and browser control.
• heddle / heddle chat attach to a live control-plane server when one exists, or start an embedded one when needed.
• heddle daemon starts the same server path as a standalone process for browser and longer-lived workflows.
• Workspaces own their local .heddle/ state, but the server does not own one global active workspace. Clients send workspace identity with workspace-scoped requests.

If you want to understand how chat, ask, the daemon, the control plane, and workspace-local state fit together, read:

• Runtime host model

Heartbeat

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.

Heartbeat keeps the latest runner result and saved run history in the same record shape, so terminal commands and the browser control plane show the same decision, summary, outcome, and usage data. Tasks can use operator-controlled continuation or agent-selected continuation depending on how much autonomy the host should allow.

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 list

Why 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

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=unknown
• drift=low
• drift=medium
• drift=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

Programmatic runtime APIs

Heddle is not only a CLI. The npm package also exposes runtime primitives such as createConversationEngine, AgentLoopRuntimeService.run(...), HeartbeatRunnerAgent.run, HeartbeatSchedulerService.runDueTasks, and FileHeartbeatTaskService 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

Install

Global install:

npm install -g @roackb2/heddle

Run without a global install:

npx @roackb2/heddle

The installed CLI command is heddle.

Requirements

• Node.js 20+
• access to at least one supported provider:
  • OpenAI account sign-in with heddle auth login openai, or OPENAI_API_KEY
  • ANTHROPIC_API_KEY for Anthropic models

Heddle intentionally does not support Anthropic consumer subscription OAuth. Use Anthropic API-key access unless Anthropic provides an approved third-party auth route.

Optional CyberLoop Integration

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 cyberloop

For one-off usage without a global install:

npx -p @roackb2/heddle -p cyberloop heddle

Documentation

Start here

• Documentation hub
• Runtime host model
• Chat and sessions guide
• CLI reference

Feature guides

• Runtime host model
• Control plane
• Heartbeat
• Knowledge persistence
• Semantic drift
• Programmatic use

Contributors

• Agent context
• Project posture
• Development and contributing
• Release convention
• Framework Vision
• Coding Agent Roadmap

Project Status

Heddle is already useful for real coding-agent workflows, but it is still evolving.

Current strengths include:

• terminal-first coding and repository workflows
• autonomous, catalog-backed workspace memory that helps the agent learn from normal usage
• explicit traces, approval previews, diff review, and local workspace state
• browser-based oversight and workspace switching 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 read-only for file review; it is not yet an editable IDE-like diff 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

Development

If you want to work on Heddle itself:

git clone https://github.com/roackb2/heddle.git
cd heddle
yarn install
yarn build
yarn test

yarn test runs the default unit and integration suites. Browser integration coverage lives under src/__tests__/browser-integration and runs on PRs; run it locally with yarn test:browser-integration.

See Development and contributing for the fuller contributor workflow.

License

Heddle is licensed under the MIT License. See LICENSE.