From 3caa2ff07a69ce4702f506789cf10ab6b005abae Mon Sep 17 00:00:00 2001 From: Amolith Date: Sat, 7 Feb 2026 14:15:46 -0700 Subject: [PATCH] feat(agents): add ntfy notification instructions Add documentation specifying how agents should notify the user when finished with tasks using the ht command to POST to ntfy.sh. Includes requirements for title, tags, and priority headers, instructions for linking to Shelley conversations when applicable, and several examples covering normal, Shelley-originated, relevant-link, and error notification scenarios. --- dot_config/AGENTS.md | 47 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/dot_config/AGENTS.md b/dot_config/AGENTS.md index 8ae58fcfead27b7336f109b1806d41e2450b9798..e5947b3cbaa3ac76cf1ea37d59857d2dd99b9e15 100644 --- a/dot_config/AGENTS.md +++ b/dot_config/AGENTS.md @@ -24,6 +24,53 @@ When I provide the URL to or number of a ticket, todo, or issue, use the appropr - todo.sr.ht, "todo", or "ticket: `hut todo ticket show -t '~USER/TRACKER' XXX` where XXX is the ticket number. I'll refer to these as todos or tickets. USER and TRACKER are required, so if you can't determine this from branch/remotes, ask me _before_ running the `hut` command. - Run `git remote -v` and notice whether any of the remotes include 'soprani.ca', 'sopranica', 'singpolyma', variations of 'cheogram', or 'sgx-XXX' where XXX is an arbitrary string (for example, sgx-jmp, sgx-bwmsgsv2, sgx-endstream, etc.). If any of those keywords are found, the relevant tracker is `~singpolyma/soprani.ca`. +## Notify me when you're finished + +If I've asked you to ntfy me when you're done or if you ever have any questions at all, please send a notification by using `ht` to POST to `https://ntfy.sh/$NTFY_TOPIC_LLM` with `-A bearer -a $NTFY_ACCESS_TOKEN`. Set the following headers: + +- **t**(itle): brief, informative, sentence-case summary of what you did (e.g. "Refactored authentication middleware in rumilo") +- **ta**(gs): comma-separated emoji shortcodes (prefer to use one). Must be a _valid_ shortcode (moss and seahorse aren't valid) or it'll be treated as a text tag instead of an emoji prefix. +- **p**(riority): only set this 1-5/min-max urgency int if something went wrong. 3 is default, so escalating would either be 4 as high or 5 as max/urgent. 4 results in a long vibration burst while 5 results in a really long vibration burst. 3 is normal. + +The body should be a slightly longer, friendly paragraph saying who is finished with what in which project. + +If `$SHELLEY_CONVERSATION_ID` is set, find this conversation's slug with `sqlite3 "$SHELLEY_DB" "SELECT slug FROM conversations WHERE conversation_id = '$SHELLEY_CONVERSATION_ID'"` and add the header `Click: https://$(hostname).shelley.exe.dev/c/`. If `$SHELLEY_CONVERSATION_ID` is not set, DO NOT link to anything unless it's relevant. + +For example + +```bash +ht POST "t:" "ta:" "" # normal example +ht POST "t:" "ta:" "" Click:https://vm-host.shelley.exe.dev/c/some-slug # from shelley +# link to something i might plausibly have asked for +# slightly more urgent example saying the disk is full or something +# normal success, not from Shelley +ht POST "https://ntfy.sh/$NTFY_TOPIC_LLM" -A bearer -a "$NTFY_ACCESS_TOKEN" \ + "t:Refactored authentication middleware in rumilo" \ + ta:hammer_and_wrench \ + "Shitty coding agent (pi) finished refactoring the auth middleware in rumilo. Session validation is cleaner now and all tests pass." + +# from Shelley, with click URL to the conversation +ht POST "https://ntfy.sh/$NTFY_TOPIC_LLM" -A bearer -a "$NTFY_ACCESS_TOKEN" \ + "t:Added HEIC upload support in shelley" \ + ta:white_check_mark \ + Click:https://vm-host.shelley.exe.dev/c/heic-upload-support \ + "Shelley finished adding HEIC-to-JPEG conversion for image uploads in shelley. The new imageutil helper handles it transparently and tests cover the happy path." + +# linking to something relevant, not from Shelley +ht POST "https://ntfy.sh/$NTFY_TOPIC_LLM" -A bearer -a "$NTFY_ACCESS_TOKEN" \ + "t:Updated AUR package for kagi-ken" \ + ta:package \ + Click:https://aur.archlinux.org/packages/kagi-ken \ + "Crush finished bumping the kagi-ken AUR package to v0.4.2 and updated the checksums." + +# something went wrong +ht POST "https://ntfy.sh/$NTFY_TOPIC_LLM" -A bearer -a "$NTFY_ACCESS_TOKEN" \ + "t:Build failed in pi-mono — disk full" \ + ta:rotating_light \ + p:4 \ + "Amp ran into a full disk on the build server while compiling pi-mono. /var/log looks like it needs rotation. The build is blocked until there's space." +``` + ## Planning before acting IMPORTANT: When I ask you to plan first, I want you to first slow down and make sure you're taking your time and deliberating prior to jumping in and fulfilling my request. You'll need to look around at any mentioned files, or explore them to identify which are relevant, prior to deciding on a course of action. Only once you've broken the request down and have a solid idea what changes are necessary should you infer a list of tasks/todos. Once you've made the plan, stop and ask me to review it. Once I explicitly confirm, you may get started.