From 2acd6b0e38e4af1fd13bad1cef8af7407b20684c Mon Sep 17 00:00:00 2001
From: t <t@tjp.lol>
Date: Tue, 18 Aug 2026 14:45:03 -0600
Subject: initial commit

---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 README.md

(limited to 'README.md')

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..18e221e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# panto-herdr
+
+`panto-herdr` reports panto lifecycle state to [Herdr](https://herdr.dev/) when
+panto is running in a Herdr pane. It reports `panto` as the agent label and
+uses `thinking`, `responding`, `compacting`, and `tool:<name>` as short status
+labels.
+
+Install it through panto's rock loader:
+
+```toml
+[extensions]
+rocks = ["panto-herdr"]
+```
+
+Then run `panto update`. Start panto in Herdr, for example:
+
+```sh
+herdr agent start panto --cwd "$PWD" -- panto
+```
+
+The extension is inert outside Herdr: it only activates when `HERDR_PANE_ID`
+is set. It invokes the local `herdr` executable asynchronously and discards
+its JSON output, so reporting does not affect the panto terminal UI.
+
+## State mapping
+
+| panto event | Herdr state |
+| --- | --- |
+| `session_start` | `idle` |
+| `user_message`, `thinking`, `compaction`, `tool_details`, `assistant_text` | `working` |
+| `assistant_text_complete` | `idle` |
+
+Current panto extensions do not receive a turn-complete or interrupt event.
+`assistant_text_complete` is therefore the best available idle boundary; an
+assistant text block followed by a tool call can show `idle` briefly before
+the next lifecycle event restores `working`. Native session restore is also
+out of scope until panto exposes a stable session reference to extensions.
+
+## Check
+
+Run the module-level check with panto's Lua runtime:
+
+```sh
+panto lua _selfcheck.lua
+```
-- 
cgit v1.3