heed
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Fail
- rm -rf — Recursive force deletion command in .github/actions/setup/action.yml
- rm -rf — Recursive force deletion command in Tests/HeedCoreTests/Fixtures/inputs/commands.json
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
A native macOS app that feels and works like a TUI, with vim keys, for running coding agents: real terminals, a worktree per task, and a tap on the shoulder when one needs you.
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

Install
brew install --cask heed-build/tap/heed
Or download the latest release
(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, andgajumps 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 aGOAL.md; new work finds its goal on its own,
and reviewers score it against bars that fit it. See 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 andzMmerges one now. The
setup wizard (Min 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.
gmis 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.
gcstarts an agent in a folder, no repo or branch, for a question;:promoteturns 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).
![]() |
![]() |
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 inattach.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 toGOAL.mdas 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.mdfirst and keep it withheed goal, taught by heed'sheed-goalskill (loaded with--plugin-dir, nothing installed);heed goal item spawnstarts 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
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), built without the app
mise run check # compile the app
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="2j<C-w>s?" types keys first (vim notation).
Documentation
docs/ is a 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 runscripts/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=<path> 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).
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:
# 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$"
# 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 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 withscripts/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.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found

