README.md

Heddle Documentation

Heddle is a terminal coding agent runtime and CLI for real project work. This docs hub is organized so humans and coding agents can read the minimum useful context first, then branch to deeper material only when needed.

Start Here

If you are new to Heddle, begin with:

• Root README for installation and product overview
• Component and deployment model for the SDK, hosted-run, Execution Host, and coding-agent mental model
• Runtime host model for how terminal chat, daemon mode, workspace identity, and the shared control-plane server fit together
• Chat and sessions for the core interactive workflow
• Agent Skills for opt-in reusable agent workflows and skill activation
• Custom Agents for turn-scoped Ask, Code, Review, and user-defined role profiles
• MCP integrations for connecting Heddle to ecosystem MCP servers
• Knowledge persistence for how Heddle learns durable workspace knowledge while it works
• Control plane for the browser UI, workspace switching, session review, task workbench, and browser composer
• Model providers for the quick provider-family compatibility matrix
• Providers and models for OpenAI, Anthropic, local models, and OpenAI-compatible gateways
• Heartbeat for scheduled/background task workflows
• CLI reference for command lookup

Agent Reading Priority

Coding agents should not read every document by default.

Always read:

1. Agent context
2. Project posture
3. The live implementation path and nearby tests for the requested change

Read only when needed:

• guides/ for user/operator workflows
• reference/ for command, config, provider, and tool details
• architecture/ for agreed code boundaries and layering
• strategy/ for long-term direction and product tradeoffs
• evaluation/ for eval prompts and behavior-checking workflows
• releases/ for release notes and release process

Guides

Task-oriented guides:

• Chat and sessions
• Agent Skills
• Custom Agents
• Runtime host model
• Control plane
• Knowledge persistence
• Semantic drift
• Heartbeat
• Heartbeat SDK examples
• Programmatic hosts
• Component and deployment model
• Durability support matrix
• Development and contributing
• Debugging
• Release convention

Reference

Reference material for commands, configuration, and runtime behavior:

• CLI reference
• Capabilities and tools
• MCP integrations
• Model providers
• Providers and models
• Project config

Architecture

Contributor-facing architecture boundaries:

• Core Layering
• Chat Layering
• Durable State
• Live Events

Project Context

Public orientation and long-term project direction:

• Project Posture
• Agent context

Longer-term strategy:

• Project Purpose
• Framework Vision
• Coding Agent Roadmap

Evaluation:

• Eval prompts

Suggested Reading Paths

I want to use Heddle in a project

1. README
2. Chat and sessions
3. Agent Skills
4. Custom Agents
5. MCP integrations
6. Knowledge persistence
7. Model providers
8. Providers and models
9. Project config

I want the browser UI and remote oversight

1. Runtime host model
2. Control plane
3. CLI reference
4. Heartbeat

I want scheduled or background agent work

1. Heartbeat
2. Control plane
3. Programmatic hosts

I want to switch between local projects

1. Control plane
2. Runtime host model
3. CLI reference

I want to build on Heddle programmatically

1. Component and deployment model to choose embedded, adopter-hosted, or separate-host execution
2. Programmatic hosts for the conversation engine, persisted sessions, and turn submission
3. Durability support matrix before choosing local or remote storage boundaries
4. Capabilities and tools
5. Providers and models

I want to contribute or develop locally

1. Agent context
2. Project Posture
3. Development and contributing
4. CLI reference
5. Framework Vision only for strategic context
6. Core Layering when changing core boundaries

I want to prepare a release

1. Release convention
2. Development and contributing
3. CLI reference