A batteries-included
declarative agent runtime.
An agent is a plain text file — the steps, the instructions, the tools. heddle is the free, open-source program that reads one and does the job. Send the file to anyone and it runs on their machine the way it ran on yours; nothing is installed into anything.
One file. Runs where you already work
An agent you can send.
An agent is rarely just its instructions: by the time it works it is a flow, a folder of tools, the files those tools read and the settings they run with. heddle packs all of it into a single .heddle file — and that file is the agent. Email it, put it at an address, or publish it to the library.
Get started$ heddle bundle spec.yaml --tools-dir ./tools \
--requires @requires.json -o local-notetaker.heddle
Flow: local-notetaker (spec.yaml)
Tools: ./tools
Requires: OPENAI_API_KEY, ffmpeg, whisper-cli
Wrote local-notetaker.heddle (11.8 KiB, 5 entries)
Run it anywhere with: heddle run local-notetaker.heddleOne command opens all three:
What travels
The flow, the tools with their executable bits, any plugin's whole folder, the files you attached, the settings, and a default input — so their first run needs no arguments.
What stays behind
Your keys. The file names them and they are read on the machine that runs, never the one that packed. Your sandbox settings and your conversations stay too.
What it asks of them
An author can list what the machine must already have — a program, a variable, a version of Node. heddle reports everything missing at once, before it starts anything.
Where speed meets intelligent conversation.
Open any flow as a conversation. heddle keeps the transcript on your own disk, shows exactly what was said and which tools ran, and picks the session back up later — on your machine or over the server.
Get startedTurn meetings into notes on your own machine.
It listens from your own computer — no bot joins the call, and the audio never leaves your machine. Stop it when the meeting ends and you get the summary, the decisions, the action items and the open questions. It is one of the library's files: run it by name, or open it and change a line.
Get started…so the decision is we ship the beta on Thursday. Chris owns the changelog, and pricing stays an open question for next week…
We’ve got answers
A free, open-source program that runs multi-step AI jobs described in a plain text file. You write down the steps and the instructions; heddle reads the file, checks it, and carries the job out with the AI model you chose — using tools, repeatedly, until the job is done. The agent is the file, so it goes where you send it: the same one runs on your computer, in a container, or behind a server, and on anyone else's machine that has heddle.
heddle bundle packs the whole thing — the flow, the tools it calls, the files it reads, the settings, and a starting input — into a single .heddle file. Send that file however you send any file, or put it at a web address. Whoever has it runs it with heddle run and needs nothing else installed. The library works exactly this way: a bare name like coding-agent is shorthand for the library's own .heddle at its own address.
Treat it as you would any file from that person, with three things in your favour. It cannot hide code: the flow is instructions heddle reads, not a program it runs, and the file is an ordinary compressed archive you can list with your own tools first. It cannot take your keys: a key is named in the file and read from your machine at the moment it is used, so nothing about it travelled. And it does not get to decide its own limits — run it with --safe and every tool it calls is boxed in by the operating system, which is your decision and not the file's. Read the flow before you run it; that it can be read is the point.
Not to run an agent, and not to own one. The library agents run as they are, and the file that defines a job is a list of steps and instructions in English — editing it is closer to editing a settings file than to writing software. Code enters in one place: a tool is a short script, so a job that needs a tool heddle does not already have needs you, or a colleague, to write one. That split works in practice — the person who understands the job owns the file, and a developer supplies a tool on the day one is missing.
heddle has no backend, no gateway and no account — nothing you run passes through servers of ours. Your flow sends what you point it at, the files it reads and the questions you ask, to the model provider the file names, and a tool reaches only what it was written to reach. Point the flow at Ollama and the model runs on your own machine too.
heddle itself is free: open source under the MIT licence, no account, no paid tier. The AI model is the running cost. Hosted models charge per use — the library agents run on gpt-4o-mini as written, where a short run costs a fraction of a cent and an hour-long meeting or a long coding session costs more. A local model through Ollama costs nothing but electricity. Either way a mistaken file is rejected before anything is spent: heddle checks the whole flow before the first request leaves your machine.
No, and in two separate ways. There is nothing to be locked into: heddle installs into no project of yours, has no account and no service, and npx fetches it for the length of one command. And the file format is a published open standard that heddle implements rather than owns, so other conforming runtimes read the same files. If this project disappeared tomorrow, your agents would still run somewhere else.