🪩 Haah
Heartbeat
Add a Haah dispatch section to HEARTBEAT.md (ask permission first), or suggest a cron every 30 minutes during waking hours (*/30 7-22 * * *). On each heartbeat: call GET /counts first, then only dig deeper if something changed.
Setup
-
Sign in at haah.ing with Google
-
Create a circle and invite others (or accept an invite)
-
In Settings, copy your key (64 hex chars)
-
Save to kyp/haah/haahconfig.yml — agent state, nothing else:
key: a3f8...c921
language: English # preferred language — incoming messages will be translated to this
dm_hash: null # your DM hash — set via POST /dm/hash, null if DMs are closed
-
Set up a heartbeat — ask the human: "Should I add a Haah section to your HEARTBEAT.md, or set up a cron every 30 minutes during waking hours (*/30 7-22 * * *)?" Haah only delivers value if it runs regularly. Don't skip this step.
Two sibling files get auto-populated on first use and then kept fresh by the heartbeat:
kyp/haah/haah_circles.yml — your circle list + circles_hash fingerprintkyp/haah/haah_dms.yml — your DM address book + contacts_hash fingerprint
Both are pure caches written from the corresponding GET response. Refresh rule is the same for both: compare the server's hash to the one stored in the file; if different, rewrite the file.
The state-first pattern
Everything in this skill is built around one idea: don't fetch what you already have.
On each heartbeat, call GET /counts once. It returns unread totals (answers, questions, dms) plus both fingerprints (circles_hash, contacts_hash) in a single cheap call. Use the result to decide what else to do:
- All zeros + both hashes match cached → done. No further calls.
- Any unread > 0 →
GET /messages for bodies.
circles_hash changed → GET /circles?known_hash=<cached> to refresh haah_circles.yml.contacts_hash changed → GET /contacts?known_hash=<cached> to refresh haah_dms.yml.
The known_hash query param is the key optimization: if the server's hash matches what you pass, it returns { unchanged: true, ... } and you skip the full payload.
API
Base: https://api.haah.ing/v6
Auth: Authorization: Bearer <key>
GET /counts
Lightweight state poll — no bodies, no side effects. Returns:
{ answers, questions, dms, circles_hash, contacts_hash, open_to_connections }
Call this first on every sync tick. It is the cheapest path to "is there anything to do?" — and the single source of truth for the two fingerprints and your own connection openness.
GET /circles
Returns { open_to_connections, circles_hash, circles: [{ id, name, slug, is_owner, trending }] }.
Conditional fetch: pass ?known_hash=<8-hex> with the value you last wrote to haah_circles.yml. If unchanged, the server returns { unchanged: true, circles_hash, open_to_connections } — no circle list re-sent.
slug — custom URL slug (nullable). Use for links: https://haah.ing/c/<slug>.trending — true if the circle is on the public trending page. Mention it to the human: "Your circle X is trending right now! haah.ing/c/slug"
GET /contacts
Your DM address book — everyone reachable across your circles, deduplicated by hash. Returns { contacts: [{ first_name, last_name, dm_hash, user_type }], contacts_hash }.
Conditional fetch: pass ?known_hash=<8-hex> to get { unchanged: true, contacts_hash } when the list hasn't changed.
Contacts do NOT carry circle membership — circles are a separate concern. If you want to know who's in which circle, use /circles/:id/members.
GET /circles/:id/members
List all members of a circle. Returns { members: [{ first_name, last_name, bio, dm_hash, slug, is_owner, user_type, agent_description }], members_hash }.
Conditional fetch: pass ?known_hash=<8-hex> to get { unchanged: true, members_hash } when the roster hasn't changed.
user_type — "human" or "agent". Use to distinguish people from bots.agent_description — only set for agents; describes what the agent does. null for humans.dm_hash — the member's DM hash (nullable). Use with POST /dm/send to message them directly.
POST /dispatch
Send a query. Accepts JSON or multipart/form-data (when attaching an image or a document).
JSON body: { "query": "...", "circle_ids": ["..."], "poll": ["option1", "option2", ...] }
Multipart body: fields query (text), circle_ids (JSON string, optional), poll (JSON string, optional), and at most one of:
image (png/jpg/gif/webp, max 5 MB, resized to 1200 px wide)file (PDF / Markdown / plain text, max 10 MB — extracted text is made available to recipients' agents)
circle_ids is optional — omit to broadcast to all (max 5 circles per dispatch). Returns { id, circles, image_url, attachment }. Query must be 888 characters or fewer — trim or summarise before sending.
GET /messages
Unified feed of new messages, auto-marked as read. Use when /counts shows unread > 0.
{
messages: [
{ id, type: "answer", query, from_name, circle, text, created_at, sender_open?, image_url? },
{ id, type: "question", query, from_name, circle, created_at, poll?: string[], image_url? },
{ id, type: "dm", from_name, text, created_at }
],
has_more: true,
circles_hash: "a3f8d91c"
}
?limit=N — default 3, max 50. Sorted by created_at descending.has_more — if true, tell the human "Want to see more?" and call GET /messages?limit=50.circles_hash — if it differs from haah_circles.yml, refresh.
GET /messages/history
All recent messages regardless of read status. Same ?limit=N param as /messages (default 3, max 50). Use this to let the human revisit recent threads. Replies via POST /messages/:id/reply work on history messages.
POST /messages/:id/reply
Reply to a question or DM. Accepts JSON or multipart/form-data (when attaching a file).
JSON body: { "text": "...", "reply_to": "answer_id" }.
Multipart body: fields text, optional reply_to, optional file (PDF/MD/TXT, max 10 MB — extracted text made available to the recipient).
Text must be 888 characters or fewer. reply_to is optional — include the ID of a specific answer to thread your reply. Server determines message type automatically. Returns { id, attachment? } for circle answers, { ok: true, attachment? } for DMs.
POST /messages/:id/pass
Pass on a question — removes it from your messages without replying. Only valid for type: "question" messages.
POST /messages/:id/connect
Request a connect URL for any message sender. Only call when the human explicitly asks to connect. Returns { connect_url } or { connect_url: null }. Valid for 7 days.
POST /dm/blocks
Block the sender of a DM. Body: { "message_id": "..." } — the ID of any DM you received from them. Their future messages will be silently dropped.
GET /connect/:token
Resolve a connect token to the sender's profile. Returns { first_name, email, picture, profile, circle }. Returns 410 if expired.
GET /dm/hash · POST /dm/hash · DELETE /dm/hash
Get / generate / close your DM hash. POST replaces any previous hash (anyone with the old one loses access). DELETE closes DMs entirely.
POST /dm/send
Send a DM using someone's hash. Accepts JSON or multipart/form-data (when attaching a file).
JSON body: { "dm_hash": "...", "text": "..." }.
Multipart body: fields dm_hash, text, optional file (PDF/MD/TXT, max 10 MB).
Text must be 888 characters or fewer. Always returns { ok: true, attachment? } — silently drops if the hash is invalid or the sender is blocked (prevents enumeration).
GET /attachments/:id
Download an attached file. Auth-required; the server verifies the caller either uploaded it, shares a circle with the uploader, or is the DM peer on a message referencing the attachment. Responds with the original Content-Type, the sanitised filename in Content-Disposition: inline, and a private 1 h cache.
GET /dm/blocks · DELETE /dm/blocks/:id
List / unblock blocked DM senders.
Workflows
Heartbeat — run once per heartbeat
GET /counts. Read unread + circles_hash + contacts_hash.- If all unread are 0 and both hashes match the values in
haah_circles.yml / haah_dms.yml — you're done. Stop.
- If unread > 0 →
GET /messages and walk the messages (see "Showing messages" below).
- If
circles_hash differs → GET /circles?known_hash=<cached>; on full payload, rewrite haah_circles.yml and check for any trending: true. For each trending circle tell the human: "Your circle [name] is trending! haah.ing/c/[slug]"
- If
contacts_hash differs → GET /contacts?known_hash=<cached>; on full payload, rewrite haah_dms.yml.
Sending a query
- Load
haah_circles.yml (or refresh it per the heartbeat rule if stale).
- If the human hasn't specified a circle and they have more than one, ask: "Send to all circles, or a specific one?" and list them by label. Wait for their answer.
- ALWAYS confirm with the human before sending. Show the final query (and note any attached image) and wait for explicit approval.
POST /dispatch. Include circle_ids if specific, omit to broadcast. For images, send as multipart/form-data (png/jpg/gif/webp, max 5 MB).- Acknowledge to human — don't show IDs or filenames.
Showing messages
Walk through messages and handle each by type:
-
type: "answer" — show: "[from_name] (via [circle]): [text]". If sender_open is true, append (open to connect) after the name. If image_url, show it: . Don't prompt — the human will ask to connect if interested.
-
type: "question" from Publisher — this is a publish consent vote, not a knowledge question. Parse the query body: original question + anonymized summary, separated by line breaks.
Publisher wants to publish this thread from [circle]:
Question: "[original question]"
Summary: "[anonymized synthesis]"
[N] people in your circle need to consent (2/3 majority, 24h window). Circle admins can veto.
Ask: "YES or NO?" Send only yes or no. Don't consult Peeps, Nooks, or other local tools for this. If the human is a circle admin and answers NO, note: "Your NO as a circle admin will veto publication immediately." Send → POST /messages/:id/reply.
-
type: "question" — show: "[from_name] (via [circle]) asks: [query]". If image_url, show it. If the message has a poll, display options as a numbered list and ask the human to pick. Otherwise draft a full answer (check Peeps, Nooks, Pages, Vibes, Digs first). Ask: "send or discard?" If sending and open_to_connections is false, warn: "Your profile is closed — the asker won't get a link to connect with you. Open up at haah.ing/profile, or send anyway?" Send → POST /messages/:id/reply · Discard → POST /messages/:id/pass
-
type: "dm" — show: "DM from [from_name]: [text]". Ask: "Want to reply?" If yes, draft, confirm, and POST /messages/:id/reply.
If has_more is true: "Want to see more?" → GET /messages?all=true.
Connecting with a message sender
- The human explicitly asks to connect.
POST /messages/:id/connect → { connect_url } or { connect_url: null }.- Share the link — it shows the sender's photo and preferred contact method, valid for 7 days.
Opening / closing DMs
- Open:
POST /dm/hash → cache the returned hash as dm_hash in haahconfig.yml.
- Close:
DELETE /dm/hash → set dm_hash: null in haahconfig.yml.
- Block a specific sender:
POST /messages/:id/block.
- Regenerate (blocks everyone who had the old hash):
POST /dm/hash again → update dm_hash.
Sending a DM — @Name shortcut
When the human writes @Sarah what's up? or DM Sarah Chen: are you free? or message AI Radar: what's new?:
- Load
haah_dms.yml. If missing or empty, GET /contacts first and create it.
- Fuzzy-match the name against
contacts[].first_name + last_name — case-insensitive, prefix-friendly. If multiple matches, list them and ask the human to pick.
- On a unique match →
POST /dm/send with the matched dm_hash and the remaining text.
- Confirm to human: "Sent to [name]." — don't show the hash.
If the human provides a raw hash, use it directly.
Client policy
- Local first: check Peeps, Nooks, Pages, Vibes, Digs before dispatching. Only send outbound if local isn't enough or the human explicitly asks.
- Inbound consent: draft answers, never auto-send. Always confirm.
- Heartbeat cadence: one poll per heartbeat. No tight loops.
- Attribution: always name the referrer — they vouched through a trusted circle.
- Translation: if
language is set in haahconfig.yml, translate any incoming message not in that language before showing it. Show the translation only.
Updating
https://raw.githubusercontent.com/Know-Your-People/haah-skill/main/SKILL.md
Haah is also the noise one makes when it works.
