Welcome to Heddle
Heddle is an open-source, local-first coding agent harness, runtime, and terminal-first workspace for traceable repository 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 gives users a review path for file diffs, commands, approvals, and traces.
In the Heddle v3 line, heddle and heddle chat open the supported API-backed terminal UI. Terminal, browser, and mobile clients now share the same local control-plane path for sessions, approvals, live status, workspace review, memory, and heartbeat tasks.
Core concepts
Workspace
The local project Heddle is operating on. By default, commands use the current directory unless you pass --cwd.
.heddle/
The workspace-local state directory for saved sessions, traces, approvals, memory notes, uploads, heartbeat tasks, and run records.
Session
A saved multi-turn conversation with model settings, reasoning effort, compacted history, queued prompts, and trace links.
Trace
A reviewable record of tool calls, command evidence, approvals, file diffs, and runtime events from an agent turn.
Approval
An operator decision for a sensitive action such as a file mutation or shell command. Heddle keeps approval state visible instead of hiding automation.
Memory
Catalog-backed markdown notes that preserve durable project knowledge, preferences, workflows, operations, and current state.
Control plane
The local browser UI and API server that terminal, browser, and mobile clients use to share sessions, review, task, and workspace state.
Heartbeat task
A durable scheduled or recurring agent task with bounded runs, checkpoints, run history, and continuation decisions.
Who Heddle is for
Heddle is for developers who want an AI coding assistant that can work inside actual repositories, keep local state, learn reusable project knowledge, and leave a review trail. It is useful for repository orientation, implementation tasks, documentation edits, test and build verification, cross-device oversight, and recurring maintenance workflows.
Heddle is not just a stateless prompt wrapper. Its product shape is a local-first coding agent harness and runtime: tools, approvals, traces, sessions, memory, and browser oversight stay explicit so the operator can understand what changed and why.
Quick Start
Major Features
Terminal Chat →
Chat with your repo from the shell.
Sessions & Continuity →
Resume work across runs.
Knowledge Persistence →
Durable per-repo memory.
Agent Skills →
Progressive instructions for tools and workflows.
Browser Automation →
Rendered page inspection and browser interaction.
MCP Integrations →
Use ecosystem MCP tools.
Control Plane →
Browser UI for workspace management.
Heartbeat Tasks →
Autonomous scheduled work cycles.
Semantic Drift →
Conversation health telemetry.