heed

heed

Run every agent. Ship every PR.

A native macOS app that feels like a TUI, with vim modes and keys, for running coding agents.
heed hosts Claude, Codex, Cursor, pi, opencode and gemini in real terminals, taps you only when one needs you,
then gets their pull requests green and merged.

Download for macOS · heed.build · Docs · Releases

CI Latest release macOS 15+

![heed: sessions on the left, agent terminals in the middle, the PR and agent events on the right](docs/images/shots/landing/main.png) ## Install ```sh brew install --cask heed-build/tap/heed ``` Or [download the latest release](https://github.com/heed-build/heed/releases/latest/download/Heed-arm64.dmg) (signed and notarized, Apple silicon), or `curl -fsSL https://heed.build/install.sh | sh`. Then press `t` on the first screen for the tour, or `:tutor` any time. ## What it does - **Every agent, one window.** Claude, Codex, Cursor, pi, opencode, gemini or any command, each in a real libghostty terminal with tabs and splits. Agents report their state through hooks (working, idle, blocked, asking, done), so heed knows who needs you, and `ga` jumps there. - **Start work in one line.** Press `o`, describe the task: heed picks the repo, makes a worktree named after it and starts the agent with your prompt; on macOS 26 with Apple Intelligence, Apple's on-device model sharpens the repo and branch guesses, on this Mac. Sessions resume where you left them after a restart. - **Goals.** Work that outlives a session gets a goal (`gG`) with a `GOAL.md`; new work finds its goal on its own, and reviewers score it against bars that fit it. See [Goals](#goals). - **Get it green.** heed watches the PRs your sessions open. Review comments, failing checks (with the failed log) and merge conflicts become items for the agent that wrote the code, sent once it is idle. Or hand conflicts and comments to GitHub's Copilot coding agent and spare your agent's tokens. - **Get it merged.** Turn merging on per PR, repo or org. Each repo gets a merge queue: GitHub's auto-merge, or heed merging itself once your rules hold (green, reviewed after the last push, quiet, gate checks, no hold label, an optional self-review). With merging off, PRs that could merge say **Ready to merge** and `zM` merges one now. The setup wizard (`M` in Repos) proposes a repo's settings from its last 30 merged PRs and its CI failures. - **Keyboard first.** NORMAL, INSERT, VISUAL, COMMAND and HINT modes, counts, relative numbers, `:` commands, and every feature a named command you can rebind. The tutor teaches it by doing, on a pretend world. The mouse works too: every command is in the menu bar and the right-click menus with its key beside it, key hints are buttons, tabs drag and panes resize. - **Worktrees that tidy up.** Create, list and remove worktrees across repos; cleanup removes only what has been quiet for days, never dirty or unpushed work, and saves each one's commits and changes as a git ref first, so History can reopen it. - **Attention.** `gm` is one feed of everything that wants you: GitHub notifications, review requests, mentions (your teams' too), your PRs and the agents waiting on you, one row per thread with every reason. Rules in config.toml boost, lower, pin, ignore or notify. - **Chats.** `gc` starts an agent in a folder, no repo or branch, for a question; `:promote` turns it into work. - **History.** What ended, with its outcome (`gh`), and from there a timeline of what happened by day (`T`), a ledger with a short summary of each piece of work (`L`), and a dashboard of what it amounted to (`D`). - **Cheap model calls, no API key.** Summaries, drafted replies and suggestions go through the agent CLIs you are already logged in to, on their cheapest model, with daily caps. Every command, GitHub call and model call heed makes is in the call log (`:log`).
Autopilot's Now: PRs by what heed does for them, a PR's green checklist, and what heed did A PR heed merges: each merge rule and the one holding it back
Watch (gw): every PR by what it needs Get it merged: the rules, and the repo's merge queue
## Goals A goal is work that outlives one session: a feature, a migration, a cleanup. Its sessions, chats and PRs belong to it, and its `GOAL.md` says what it is, what it is not, when it is done, what is open and what was decided. `gG` opens Goals. - **It finds its work.** New sessions and chats go on their goal by themselves when heed is sure, from free signals (worktree, branch, PRs, files, the prompt) and a cheap model call when unsure; otherwise heed asks once, with one key. Corrections become rules in `attach.rules`. - **Items on a board.** heed breaks the goal into items and moves them on evidence: a session on one, a review, a PR, a merge. Edits that record what happened apply to `GOAL.md` as versions you can undo; edits that change the goal wait for you. - **Quality bars.** Each goal gets the bars it needs (a spike is not a public API), reviewers that never edit your code score the work against them within a daily budget, and stranger walks time a first run in a fresh clone. When every criterion and bar is met, heed marks the goal done. - **Personas.** Who the goal needs now, from its board, and one key to start a session, chat or reviewer as them. - **Agents keep it.** claude and codex on a goal read `GOAL.md` first and keep it with `heed goal`, taught by heed's `heed-goal` skill (loaded with `--plugin-dir`, nothing installed); `heed goal item spawn` starts work on an item. - **Colleagues follow along.** Mirror a goal (`M`) to a tracker repo as a meta issue with a sub-issue per item; their changes come back as questions for you. - **Swarms.** A lead agent plans the goal, you approve the plan, and workers take its tasks in parallel, each in a worktree of its own; their PRs stack on each other and merge in order. Questions go to whoever may answer them (a peer, heed's controller, you), a stuck worker is nudged and helped on its own, the agents pane and a map show how it goes, and a done swarm writes its end-of-build summary. heed keeps a record of each session (its timeline, outcome and summary, in SQLite); the agents own their transcripts. It is macOS only and not sandboxed: it has to spawn shells, git and agents. ## Development ```sh mise install # zig (libghostty), swiftformat, swiftlint mise run doctor # what is missing: Xcode licence, Metal toolchain, zig, gh mise run ghostty # build Vendor/GhosttyKit.xcframework from the pinned Ghostty commit mise run dev # build, assemble build/Heed.app, copy it to HEED_DEPLOY_DIR, launch mise run test # Swift Testing (HeedCore) mise run lint # swiftformat + swiftlint ``` Without GhosttyKit the app builds with placeholder panes, so everything but the terminal can be worked on. Headless checks: `HEED_SNAPSHOT=out.png build/Heed.app/Contents/MacOS/Heed` renders the window to a PNG and quits; `HEED_SNAPSHOT_KEYS="2js?"` types keys first (vim notation). ## Documentation `docs/` is a [docs-builder](https://github.com/elastic/docs-builder) site published to heed.build by `.github/workflows/docs.yml`; `docs/heed-landing.html` is a standalone page copied over the generated home page. `mise run docs` builds it the same way and serves it on :4000 (`docs-builder serve` would skip the landing page). Both build with docs-builder's design-system layout (`FEATURE_NAVIGATION_PREVIEW=true`), then run `scripts/docs-finish.sh`, which appends the heed theme (`docs/heed-docs.css`) to its stylesheet and patches the pages (`scripts/docs-pages.py`). `DOCS_BUILDER= mise run docs` builds with a local docs-builder binary. ## Outside the window - `⌃⌥H` (`[keys] global_activate`) brings Heed to the front from any app, reopening the window if it was closed. - The menu bar owl (`[ui] menu_bar`, on by default) shows how many sessions need you; its menu lists them (choosing one opens Heed on it), plus Start work, Open Heed, Settings and Quit. With it on, closing the window keeps Heed and its agents running. - The Dock icon (`[ui] dock_state`, on by default) gets a badge in the state's colour (blocked, else asking) with the count. - A notification (`[notifications]`, on by default) when a session, a helper tab or a PR has needed you for 30 seconds, unless Heed is in front on it, and one reminder after 15 minutes; a burst comes as one. Attention items a rule says to notify about get one too. None during quiet hours (`[attention] quiet`). Open brings Heed forward on the session; a Claude permission prompt also gets Allow. The brand pack (icon, logo, menu bar template, social preview, org avatars) lives in `design/brand/`. Other apps and scripts drive Heed through `control.sock`: `heed start`, `send`, `show`, `sessions` and `watch` (see [the CLI reference](https://heed.build/reference/cli/)). ## Start work from anywhere `⌃⌥Space` (`[keys] global_start_work` in config.toml; `""` turns it off) opens Start work in a floating panel over whatever app is in front. It takes the keyboard without bringing Heed forward; `⎋ ⎋` or a click elsewhere closes it, `⌘↩` starts the session. The panel's window title is always `Heed Start Work` (bundle id `build.heed.app`), so a tiling window manager can leave it alone: ```toml # OmniWM: ~/.config/omniwm/settings.toml (id is any UUID) [[appRules]] bundleId = "build.heed.app" id = "75CF2DF1-FF34-4187-9CC9-01DD190EFC51" layout = "float" titleRegex = "^Heed Start Work$" ``` ```sh # yabai yabai -m rule --add app="^Heed$" title="^Heed Start Work$" manage=off ``` ## Layout | Path | What | | --- | --- | | `Sources/HeedCore` | No UI: key notation, keymaps, the mode engine, commands, sessions, pane trees, the hook protocol | | `Sources/HeedApp` | SwiftUI shell, AppKit key routing (`Keys/KeyRouter.swift`), terminal hosting (`Terminal/`) | | `Sources/HeedTerminal` | The libghostty wrapper; the only code that touches `ghostty.h` (built when GhosttyKit exists) | | `Sources/heed` | The CLI agent hooks call: `heed state blocked --reason "..."` over a unix socket, spooled while the app is closed | | `design/` | The approved boards (`screens/*.png`) and the original brief (`BRIEF.md`) | | `PLAN.md` | The plan, decisions and build order | ## Contributing and releasing `main` only changes through pull requests, and CI must pass: lint, the tests, a release build and the tutor check on macOS, and the docs build. Branch names label pull requests for the release notes: `feature/…`, `fix/…`, `docs/…`. [release-drafter](https://github.com/release-drafter/release-drafter) keeps a draft release up to date as pull requests merge, and works out the next version from their labels (`major`, `minor` or `enhancement`, otherwise a patch). To release, run the **release** workflow (`gh workflow run release`, optionally `-f version=0.2.0`): it builds `main`, signs it with the Developer ID (hardened runtime, `scripts/sign.sh`), has Apple notarize it and staples the ticket, builds the drag-to-Applications disk image (`scripts/dmg.sh`, laid out by dmgbuild over `packaging/dmg/`) and has it notarized and stapled too (`scripts/notarize.sh`), attaches `Heed-arm64.dmg`, `Heed-arm64.zip` and their sha256 files to the draft, checks they are all there, and only then publishes the draft, which tags the commit it built. A rejected notarization stops it before anything is attached. `-f dry_run=true` does all but the release, from any branch, and keeps the notarized zip and disk image on the run. It then writes the cask (`packaging/homebrew/heed.rb`) to [heed-build/homebrew-tap](https://github.com/heed-build/homebrew-tap) with `scripts/bump-tap.sh`; the **tap** workflow redoes that by hand. `install.sh` installs from the latest release. The signing and notarization secrets come from `scripts/release-secrets.sh`. The **notary** workflow asks Apple how submissions are doing. Until the first release exists, **notary-watch** checks every two hours and starts the release itself once Apple accepts a submission (a new Developer ID's first notarizations can take hours or days), then turns itself off. ## Deploying to the MacBook `mise run build` copies `build/Heed.app` to `$HEED_DEPLOY_DIR` (set in `mise.local.toml`, not committed). Skipped, never failed, when the share is not mounted. ## License heed is free and open source under the [MIT license](LICENSE).