# moth harness adapters

Each adapter sends the coding agent's **final reply of a turn** to the running moth server, one way:
`POST $MOTH_URL/api/agent` with `{"text": "<raw markdown>", "source": "claude-code", "session": "<id>", "label":
"moth-repo"}`. `source` is the harness name; `session` is a stable id of the agent session and `label` a short name for
it, the basename of its working directory (else the first 8 characters of the session id). Cards show them as
"claude · moth-repo said…" in moth's page and `moth tail`. `session` and `label` are optional: an older adapter
without them counts as one session per harness. `MOTH_URL` defaults to `http://127.0.0.1:4747`.

Every adapter follows the same rules:
- It uses a 1 s timeout and never throws or prints. The JS and Hermes adapters never wait inside the agent's own code
  path; the Claude Code and Codex hooks run in the foreground, so a one-shot run can't kill them before they post
  (the wait is the hook's start-up plus one local POST that moth only queues, 1 s at most).
- It posts nothing when moth is down. If moth is slow, it hangs up after 1 s, but moth keeps the text: `serve.py`
  reads the request body first and the page polls `/api/log`.
- It posts nothing for subagent turns, aborted turns, or turns with no assistant text. It never re-sends an older reply.
- It needs no dependencies beyond Python's stdlib or the harness's own JS runtime (`fetch`).
- It sends moth's per-install token (`X-Moth-Token`, read from `~/.moth/token` on every post; moth makes the file on
  its first run, `MOTH_TOKEN_FILE` overrides). Python adapters bypass any HTTP proxy set in the environment.

moth doesn't react to every turn: at most one reaction per 2 minutes (`--react-every`), except when the agent
apologises, reports a failure or an error, or writes a very long message. While you're chatting with moth (the last
60 s, `--quiet-after`) it holds its reaction until you stop. Every turn still shows up as a card; only ~25 words of
each one stay in moth's memory after it reacted, so agent turns don't push your conversation out.

Several sessions at once (any mix of harnesses):
- **Batching.** When moth may react, it first waits `--batch-window` seconds (default 4) for other sessions to finish
  too. Then it reacts to the most interesting message: a failure, apology or error first, then a question to you,
  then a long message, then a routine "done" (the newest wins a tie). The others show as skipped cards. Batched cards
  appear when the window closes, the chosen one last, so moth's reply sits right under it. `--batch-window 0` turns
  this off, and `--react-every 0 --quiet-after 0` (the judge tooling) still reacts to every message at once, with no
  window.
- **No mix-ups.** moth's history keeps one agent turn per session: when it reacts to session B, the older agent
  turns of B, and all but the newest of every other session, are dropped together with moth's replies to them (agent
  turns carry a session marker in the history that the model never sees). moth's input stays exactly what it
  trained on (`[the agent said]` + the message); session names never go into it.
- **Seeing them.** The page shows "2 agents active · 1 skipped" (sessions that posted in the last 30 min) and, with
  two or more sessions, a dropdown to show one session's cards (moth's replies always show). `moth tail --session
  <label>` does the same in a terminal. When two active sessions share a folder name, moth adds the end of the
  session id: "moth (3f2a)".
- Synthetic batch turns ("three tasks finished, one says sorry") were left out on purpose: moth only ever trained on
  real agent messages, and a counted summary would be out of distribution. It couldn't be tested here without
  running the model.

| Harness | `session` | `label` from |
|---|---|---|
| Claude Code | Stop input `session_id` | Stop input `cwd` |
| Codex CLI | Stop `session_id` / notify `thread-id` | `cwd` (both) |
| Hermes Agent | `post_llm_call` `session_id` | `agent.runtime_cwd`: gateway session cwd, else `TERMINAL_CWD`, else launch dir |
| Pi | `ctx.sessionManager.getSessionId()` | `ctx.cwd` |
| OpenCode | the event's `sessionID` | `Session.directory` (from `session.created/updated`), else the plugin's `directory` |
| dsh | `session.id` | `process.cwd()` (dsh is started in the project) |

moth has to be awake for the adapters to reach it. The one-command way is the desktop pet,
`cd moth-112m/code && python -m moth.pet`: it starts the server itself and stops it when you quit the pet. For the
snippets, or without a desktop, run `cd moth-112m/code && python -m moth` (just the server, in the terminal; the pet
uses it if it's already running). It prints the snippets below with the real absolute paths
of your copy filled in. The chat page is served at `http://127.0.0.1:4747/` but only opened in your browser with
`python -m moth --open` (or `--browser`; the old `--no-browser` is accepted and does nothing). Below, paths are
relative to the Hugging Face download (`hf download darioooooo0o/moth-112m --local-dir moth-112m`); hooks need
absolute paths, so put your own folder in front of `moth-112m/`.

| Harness | File | Mechanism | Turn-end event |
|---|---|---|---|
| Claude Code | `claude_code.py` | command hook | `Stop` |
| Codex CLI | `codex.py` | hooks.json command hook, or legacy `notify` | `Stop` / `agent-turn-complete` |
| Hermes Agent | `hermes/moth/` | plugin | `post_llm_call` |
| Pi | `pi/moth.ts` | extension | `agent_end` + `agent_settled` |
| OpenCode | `opencode/moth.js` | plugin | `session.status` idle (+ deprecated `session.idle`) |
| dsh | `dsh/moth.mjs` | cordis plugin | `session/event` → `turn/end` |

Test them all offline against a stub moth: `python3 moth/integrations/test_integrations.py` (about 50 s, 127.0.0.1 only).

**Or let moth install them** (from `moth-112m/code`, or anywhere after `pip install`, as `moth ...`):
- `python -m moth hooks` lists the harnesses found on this machine and whether moth is hooked into each. It also
  flags copies that are outdated, broken or point to another moth folder.
- `python -m moth hook claude-code` (or `codex`, `hermes`, `pi`, `opencode`, `dsh`, or `--all` for every harness
  found) does what the sections below describe. It shows the plan and asks first (`--yes` skips the question,
  `--dry-run` only shows the plan), then prints what changed.
  - Every config file it edits is backed up first as `<file>.bak-moth-<timestamp>`. JSON, YAML and TOML configs are
    merged, so other hooks and keys stay. Installing twice changes nothing.
  - Copied adapters (Pi, OpenCode, Hermes) that differ from this folder's copy are replaced, for example after an
    update. The old Hermes folder is kept in `~/.moth/backups/`, outside the plugins folder.
  - Codex: the `hooks.json` hook by default, or `--legacy-notify`. moth never installs both. Approve the hook once in
    `codex` (`/hooks`).
  - `--project DIR`: Claude Code's `DIR/.claude/settings.json`. `--profile NAME`: the dsh profile.
- `python -m moth unhook <harness>|--all` removes moth's entries only. It deletes a copied adapter only if it is
  moth's.

## Privacy: what moth sees, and where it goes

- **What moth sees: two things only.**
  - The final message of each agent turn, posted by the adapters above. Each post carries a session id and the
    project folder's name as its label.
  - What you type to moth: in the chat page, the pet, `moth tail`, Pi's `/moth` or the Claude Code band.

  It never gets your prompts to the agent, the agent's tool calls, or your files. Its own tools reach only its home
  folder.
- **Everything stays on your machine.** The server listens on 127.0.0.1 only, unless you start it with another
  `--host`. The adapters post to `http://127.0.0.1:4747`, unless you set `MOTH_URL`.
  - moth's code goes online for two things only, both from the Hugging Face Hub: downloading the weights (first run
    of a pip install) and `moth update`.
  - The browser chat page embeds its two fonts, so opening it doesn't fetch anything from outside either.
  - The training and eval scripts in `code/moth/` talk to whatever LLM server you point them at. Running moth never
    uses them.
- **Where it's stored: `~/.moth/`.** That holds the token, `config.json`, pidfiles while moth runs, `backups/` from
  `moth hook`, and moth's home folder `home/`: its files, its diary, and anything it wrote down from your chats.
  - `serve.log` holds the server's output when the pet starts it: status lines and errors, no chat text.
  - The conversation itself lives only in RAM. Stopping moth wipes it, and so does the page's "new chat" button.
    moth's memory of its own last 16 reactions (token ids, so it doesn't repeat a joke) is RAM-only too. "New chat"
    keeps it; stopping moth or `moth forget` wipes it.
  - In the dev checkout, the home is `live/home/` and the logs are `live/*.log`.
- **The agent never receives anything back.** The adapters only post. They ignore the answer, print nothing and
  exit 0, so nothing reaches the agent's context.
  - moth's lines show only in displays you turn on: the pet, `moth tail`, the Claude Code band, and the Pi widget or
    OpenCode toast with `show_in_harness on`. None of them feed the model.
  - What you say to moth goes to moth only.
- **Wiping it.** Stop moth first, then:
  - `moth forget` deletes its logs.
  - `moth forget --all` also resets its home folder, but only a folder moth made itself.
  - `moth forget --all --token` also deletes the token and settings.
  - On a moth that's still running, `moth forget` deletes no files but makes it forget the chat and its last
    reactions (`POST /api/reset {"everything": true}`).

  `moth unhook --all` removes the hooks.

## Seeing and talking to moth

The adapters above only *tell* moth about each turn. They hang up after 1 s and never see its reply. The pieces
below are the other half: they **show** what moth says back, and they let you talk to it. Each one polls
`GET /api/says` (or the full `/api/log`) for new `say` events and **never posts to `/api/agent`**, so moth never
hears a turn twice. Install
the adapter for your harness as well.

**Each in-harness display shows moth's reaction to its own session only.** With several agents running, moth's
newest line is often its reply to another one (seen live: Claude Code's band showed moth's reply to Hermes). So the
Claude Code band, the Pi widget and the OpenCode toast ask `/api/says?source=<harness>&session=<id>` for the
session they belong to, and show nothing rather than another session's line. The Hermes Desktop pet asks for
`source=hermes` (every Hermes session in that app: the renderer can't map its sessions to the agent's ids). The
desktop pet, `moth tail` and the chat page still show everything. Codex and dsh have no in-harness display.

moth needs a moment to think. A display that waits after a turn (Pi, OpenCode, when turned on) waits up to about
4 s. A slower line is not lost: it shows on the next poll, after the next turn, or right away in `moth tail` and the
pet.

**Venting stays private.** Whatever you say to moth, and what moth says back, never enters the agent's context.
That is why there is no `/moth` in Claude Code or Hermes. In Claude Code a command's output row is read by the model.
In the Hermes gateway, a plugin command sent mid-turn is handed to the running agent. Pi's `/moth` is kept, because
Pi runs extension commands outside the conversation (details per harness below).

**The server only talks to this machine, and to whoever has the token.**
- It answers only requests whose `Host` is `127.0.0.1:<port>` or `localhost:<port>`, so a website that points its
  own domain at 127.0.0.1 (DNS rebinding) gets a 403.
- `POST /api/chat`, `/api/agent` and `/api/reset`, and the full log (`GET /api/log`, every agent reply and everything
  you typed) need the token in `X-Moth-Token`. The page moth serves has it built in; the adapters and `moth tail`
  read `~/.moth/token`.
- `GET /api/says?since=n` is moth's own lines and nothing else, without a token. That is all a display needs, and
  what the Hermes Desktop pet and the Pi / OpenCode / Claude Code displays use. `&source=<harness>` and/or
  `&session=<id>` keep only moth's reactions to that harness / session (moth tags each reaction in its log with the
  turn it answers; chat replies have no tag, so they drop out). The answer is the same `{"say"}` list either way,
  with no ids or labels in it, and `next` still counts every event.
- CORS: local pages (`http(s)://localhost` or `127.0.0.1`, any port) may read answers. Desktop shells
  (`app://…`, `file://`, `null`: Hermes Desktop packaged loads `file://…/index.html`, which sends `Origin: null`)
  may read `/api/says` only. Any other origin gets no CORS header, and a POST from a foreign origin, `null`
  included, is refused outright.
- POSTs must be `Content-Type: application/json`, at most 64 KB, a JSON object; anything else gets a 4xx, not a crash.
  Every answer carries `X-Frame-Options: DENY`.
- Every poll answer has an `epoch` that changes when moth restarts or the chat is reset. Pass it back
  (`?since=n&epoch=e`) and a changed epoch gets you the new log from its start.

### In-harness display: off by default (`show_in_harness`)

The Pi widget and the OpenCode toast come inside adapters you install anyway, so they are **off** until you turn
them on. Off, those adapters still post every turn (the desktop pet and `moth tail` react as usual); they just don't
poll moth or draw anything in the harness.

```bash
cd moth-112m/code && python -m moth config show_in_harness on     # or off
cd moth-112m/code && python -m moth config                        # print the settings and where they come from
```

- Stored as `"show_in_harness": true|false` in `~/.moth/config.json` (`MOTH_CONFIG_FILE` overrides the path). The
  CLI writes it atomically and keeps any other keys.
- The adapters read the file at **every turn**, so a change applies from the next turn without restarting Pi or
  OpenCode. Turning it off also takes down a Pi widget that is on screen.
- `MOTH_SHOW_IN_HARNESS=1` / `0` (also on/off, true/false, yes/no) in the harness's environment beats the file. The
  environment is fixed when the harness starts.
- **Pi `/moth <text>`** is always registered, because Pi registers commands when it loads the extension and so can't
  follow a live toggle. Typing it is an explicit request, so it always answers. With the setting on the answer goes in
  the widget; with it off it comes as a one-off notice, and no widget is left behind.
- **Not governed by it**: the Claude Code band mod (loaded only with `--plugin-dir` or `CLAUDE_CODE_PLUGIN_DIRS`) and
  the Hermes Desktop pet half (starts disabled; you enable it in the desktop's Plugins page). Loading or enabling them
  is their opt-in, and unloading or disabling them turns them off. Honouring a default-off setting would hide them
  from someone who just loaded them on purpose. The Hermes renderer also has no file or environment access to read
  it. `moth tail` and the desktop pet are separate programs you start yourself (the pet starts the server too).

### `moth tail`: works with every harness (Codex included)

Run it in a tmux split or a terminal next to the harness:

```bash
cd moth-112m/code && python -m moth.tail            # moth's lines + a "you>" prompt to chat with it
cd moth-112m/code && python -m moth.tail --watch    # status pane only, no prompt
tmux split-window -h -l 45 'cd moth-112m/code && python -m moth.tail'    # e.g. beside codex / claude
```

- It prints moth's new lines (`moth>` in lamp yellow, wrapped to the pane), a dim `agent said: ...` one-liner for
  each turn moth heard, and a dim `$ cmd` line when moth uses a tool. It shows the last 3 events on connect
  (`--history N`).
- Lines you type go to `/api/chat`, and the reply arrives through the same poll. A moth line that arrives while you
  type is printed above the prompt, and your half-typed text is kept.
- When moth is down it prints "moth is asleep" once and retries with backoff (up to 10 s). It follows moth across
  restarts and `/api/reset`.
- Stdlib only. It doesn't import torch, so any `python3` works. `--url` or `MOTH_URL` changes the address.

### Desktop pet: a moth flying around your screen (`python -m moth.pet`, any harness)

```bash
pip install PySide6                              # optional: only the pet needs it, moth itself doesn't
cd moth-112m/code && python -m moth.pet          # --size 64, --no-wander (sits in a corner), --url, --token-file
python -m moth.pet -- --react-every 0            # flags after -- go to the server the pet starts
python -m moth.pet --export-petdex ./moth-pet    # the same moth as a Petdex / Codex pet (pet.json + spritesheet.png)
python -m moth.pet --skin <pet-id>               # wear an installed Petdex pet instead (or --skin ./some-pet-folder)
python -m moth config pet_skin <pet-id>          # ... every time (default moth); update_check on|off for the bubble
```

- **One command.** At start the pet asks `GET /api/health` on its URL. If a moth answers, it uses that one and never
  stops it. If nothing listens, it starts `python -m moth.serve` itself (same Python, CPU, this download's weights),
  dozes with "waking up…" while the model loads, and stops that server again when the pet quits (menu quit,
  Ctrl-C, SIGTERM/SIGHUP, the window closed; on Linux also if the pet is killed). The server runs in its own process
  group and logs to `~/.moth/serve.log`. If something that isn't moth holds the port, or less than ~3 GB of memory
  is free, it starts nothing and says why in the bubble.
- Flags: `--no-server` (never start one, just wait for moth like before), `--model DIR` (the weights for a server
  the pet starts), `--server-arg=--flag` (repeatable; `--server-arg=--react-every --server-arg=0`) or anything after
  `--` for that server. `python -m moth` / `python -m moth.serve` are still the way to run moth headless or in a
  terminal.

- A small moth, drawn in the page's style, flies around on top of your windows. It drifts, is drawn to the mouse
  cursor, lands on screen edges to rest, and dozes after 3 idle minutes. When a new line arrives it flutters and says
  the line in a speech bubble (wrapped at 32 characters, shown for 6-10 s, queued). When `~/.moth/token` is
  readable, a reaction gets a small `claude · repo` caption, taken from `/api/log`. Without the token the pet uses
  `/api/says`.
- Click the moth to type to it (`/api/chat`, needs the token); the reply comes back in the bubble. Drag it to move
  it. Right-click for: open chat page, mute bubbles, sleep, show moth in harnesses, skin, check for updates, quit.
  It never takes focus, except for that input box. Where the desktop has a system tray, a tray icon has the same
  menu (no tray, e.g. on some Wayland setups: no icon, the right-click menu is still there).
- **Skins.** `--skin ID|FOLDER`, `python -m moth config pet_skin ID` or right-click → skin: the pet can look like any
  Petdex pet you have installed (`npx petdex install <pet>`). Ids are looked up in `~/.petdex/pets/<id>/`, then
  `$CODEX_HOME/pets/<id>/` and `~/.hermes/pets/<id>/`; the menu lists them all. The pet's sheet must be the Petdex
  1536x1872 grid. Flying uses running-right / running-left, resting idle, dozing waiting, excited jumping or waving,
  waiting for a reply review; the bubble sits on the pet's visible top. A missing or broken pet means moth, and the
  bubble says why. moth ships no third-party pets; they keep their own licences.
- **Update bubble.** Once a day (and on "check for updates") the pet runs `python -m moth update --check` in the
  background and, if there's a new version, says so: "run `python -m moth update`", or `pip install -U
  moth-companion` for a pip install. It never updates anything itself. Off: `python -m moth config update_check
  off`; `HF_HUB_OFFLINE=1` or `MOTH_OFFLINE=1` also skips it.
- When moth is down it dozes with "zzz… (moth server asleep)" and retries with backoff (up to 30 s). If the server
  the pet started dies, the bubble points at its log instead.
- Wayland doesn't let an app place its own window. On a Wayland session the pet asks Qt for XWayland
  (`QT_QPA_PLATFORM=xcb;wayland`, only if you haven't set it); without XWayland it stays where the compositor puts
  it (drag still works). Under XWayland the cursor position only updates over X windows, so the pull to the
  cursor fades when the cursor seems to stop. It lands on screen edges, not on other windows' edges.
- `--export-petdex DIR` writes a 1536x1872 sheet (8x9 cells of 192x208: idle, running-right/left, waving, jumping,
  failed, waiting, running, review). Copy DIR to `$CODEX_HOME/pets/moth` (Codex, pick it in `/pets`), to
  `~/.hermes/pets/moth` (`hermes pets select moth`), or to `~/.petdex/pets/moth` (the Petdex desktop app). Codex picks pets by folder name
  (`custom:moth`).
- The pet only reads moth and posts what you type; it never posts to `/api/agent`.

### Claude Code: band above the prompt, with a field to talk to moth (mod)

`claude_code_mod/` is a mod (function hooks, early-access API). It draws moth's newest reaction to this session in
the band above the prompt (`/api/says?source=claude-code&session=<$.session.id()>`, the Stop hook's `session_id`,
read on every poll so `/clear` follows), polling every 2 s, with a text field under it. The reply to what you type
there comes back with the send. Focus the band with ctrl+x tab or a click, type, and press
Enter. Esc returns to the prompt. Keep the `Stop` hook above as well, since it is what tells moth about each turn.
Try it for one session:

```bash
claude --plugin-dir moth-112m/code/moth/integrations/claude_code_mod
```

To load it in every session, add the folder to `CLAUDE_CODE_PLUGIN_DIRS` in the `env` block of
`~/.claude/settings.json` (`"CLAUDE_CODE_PLUGIN_DIRS": "/abs/path/to/moth-112m/code/moth/integrations/claude_code_mod"`).
- `MOTH_URL` changes the address. It is read when the session starts.
- **Kept out of Claude's context.** The field's Enter goes to the mod's own `onSubmit`, which POSTs to moth
  directly. The type definitions say an Input's submit starts "No model turn unless it asks one" (`InputProps.onSubmit`
  in the 2.1.302 `claude-code.d.ts`), and the band is drawn UI, not a transcript row. A slash command was rejected
  because its output is "the row the model also reads" (`CommandRunResult.text`), and a `prompt.submit` `{ drop }`
  comes too late for a plugin command, which has already run by then.
- Mobile has no `Input`, so there the band shows moth's line only.
- It reads moth's lines from `/api/says`; a send reads the token from `~/.moth/token` (`$.fs.read`).
- `claude plugin validate moth-112m/code/moth/integrations/claude_code_mod` passes on 2.1.302.

### Hermes: desktop pet (chat in `moth tail`)

- **No `/moth`.** A `register_command` reply is not added to the agent history when Hermes is idle (CLI
  `_run_plugin_slash_command` only prints it; the gateway's idle path returns before a turn). But in the messaging
  gateway, a plugin command sent while a turn runs never reaches the plugin. `resolve_command` knows only built-ins,
  so `_hm_busy_slash_or_photo` lets it fall through to `_hm_busy_steer` / `_hm_busy_interrupt`, which hand
  `/moth …` to the running agent as text (`gateway/run_inbound.py`). The hooks that run earlier don't fix this:
  `pre_gateway_dispatch` runs before auth, and `post_gateway_admission` runs after the busy lane. So chat with moth
  in `moth tail`.
- **`desktop/plugin.js`**, the Hermes Desktop half. It shows moth's lines in the pet's speech bubble
  (`ctx.pet.say`): one line at a time under a stable id, so each new line replaces the last; lines over 120
  characters are cut into up to 3 pieces shown one after another, each up for 4–30 s. It polls every 2.5 s with
  `ctx.setInterval`, for moth's reactions to Hermes turns only (`source=hermes`). It can't narrow that to one Hermes
  session: the desktop's gateway events carry the TUI session id, while the agent posts its session key
  (`tui_gateway` `_make_agent(sid, key, session_id=key)`).

The install is the same `cp -r` as above. Hermes Desktop copies `plugins/moth/desktop/` into
`<hermes home>/desktop-plugins/moth/`, and such a half starts **disabled**. Enable "moth" in the desktop's Plugins
page, and turn the pet on in Settings. The desktop half reads `http://127.0.0.1:4747` (the renderer has no
environment, so edit `MOTH` in `plugin.js` to change it). Hermes's own desktop lint
(`hermes_cli/plugin_validate_desktop.py`) finds nothing in it.

### Pi: widget above the editor + `/moth`

`pi/moth.ts` now also:
- with `show_in_harness` on (see above), polls the log for up to 4 s after each posted turn and puts moth's
  reaction to this session in a widget above the editor (`ctx.ui.setWidget("moth", ...)`, interactive sessions
  only; `source=pi&session=<getSessionId()>`, nothing without a session id);
- registers `/moth <text>`, which shows the reply in the same widget (or as a notice where there is no widget, or
  when `show_in_harness` is off).
  **Kept out of the agent's context.** `AgentSession.prompt()` runs an extension command's handler and returns
  before any message is made (`dist/core/agent-session.js` `_tryExecuteExtensionCommand`), and interactive mode
  sends input typed mid-stream and during compaction through `prompt()` too (`dist/modes/interactive/interactive-mode.js`).
  The handler only calls `ctx.ui`. The typed line is kept only in the editor's local up-arrow history.

The install is unchanged. The poll timers are unref'd, so `pi -p` doesn't wait on them.

### OpenCode: toast

With `show_in_harness` on (see above), `opencode/moth.js` also polls the log for up to 4 s after posting and shows
moth's reaction to that session as a TUI toast (`client.tui.showToast`, title "moth", 8 s;
`source=opencode&session=<sessionID>`, with a cursor per session, so two sessions in one OpenCode each get theirs). The install is unchanged. There is no `/moth` here: use `moth tail` to
chat.

### dsh: not built (options)

- **A client slot in our cordis plugin.** `dsh/moth.mjs` could poll `/api/says` after `turn/end` and hand moth's
  line to whatever display surface dsh exposes to plugins, the same way as Pi's widget.
- **`@linxin666/dsh-pet`.** If that pet plugin is installed, its announce call could carry moth's line.

Neither was checked against dsh sources (dsh isn't installed here). Until then, use `moth tail` next to dsh.

---

## Claude Code

Add this to `~/.claude/settings.json`, or to a project's `.claude/settings.json`, merging with any `hooks` already there:

```json
{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "python3 /abs/path/to/moth-112m/code/moth/integrations/claude_code.py", "timeout": 3 } ] }
    ]
  }
}
```

- The Stop input carries `last_assistant_message`, "the text content of Claude's final response". The docs advise
  using it instead of `transcript_path`, which "isn't guaranteed to include the final message at Stop time".
  The transcript is only a fallback for older versions that don't send the key, and even then only the
  current turn is read.
- Subagents fire `SubagentStop`, not `Stop`, so they are skipped.
- **No `"async": true`.** A background hook works in the interactive TUI, but a one-shot `claude -p` kills it when
  it exits, before it posts (seen live on 2.1.302). In the foreground the hook posts first. It is quick: Python's
  start-up plus one POST to 127.0.0.1, which moth only queues, and it gives up after 1 s (`timeout: 3` is Claude
  Code's hard stop). `moth hook claude-code` rewrites an older `async: true` entry, and `moth hooks` flags it as
  outdated.
- Source: <https://code.claude.com/docs/en/hooks> (Stop input, SubagentStop input, command hook fields). The field
  is also present in the local binary, 2.1.302.

## Codex CLI

**Install one of the two options below, not both**, or every reply will be posted twice.

**A. Stop hook (preferred).** Create or merge `~/.codex/hooks.json`:

```json
{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "python3 /abs/path/to/moth-112m/code/moth/integrations/codex.py", "timeout": 3 } ] }
    ]
  }
}
```

Then start the interactive `codex` once and approve the hook in the startup hook review, or later with `/hooks`.
Untrusted or modified user hooks are silently skipped, including in `codex exec`. Approval stores a
`trusted_hash` in the config, so **any edit of the entry needs a new approval** (even `async` true → false).
- **No `"async": true`**, as for Claude Code: `codex exec` drops a background hook when it exits, before it posts (seen
  live on 0.163.0; the interactive TUI posted either way). `moth hook codex` rewrites an older `async: true` entry;
  approve it again afterwards.
- **Windows:** Codex runs hook commands through PowerShell (`powershell -NoProfile -Command <command>`, the session's
  shell: `core/src/session/mod.rs` `build_hooks_config`). There a command that starts with a quoted path is a string,
  not a call, so a Python path with a space (`C:/Program Files/...`, a venv under `C:/Users/First Last`) needs the call
  operator: `& "C:/Program Files/Python312/python.exe" "C:/.../codex.py"`. `moth hook codex` writes that (and
  `moth hooks` flags an older entry without it); without it Codex ran nothing, silently (seen in `tests/e2e`).
- Hooks are a stable feature, enabled by default (`features/src/lib.rs`, `CodexHooks`, key `hooks`, at
  `rust-v0.163.0`). They are loaded from `<config folder>/hooks.json` (`hooks/src/engine/discovery.rs`).
- The Stop input carries `last_assistant_message` (`hooks/src/events/stop.rs`).
- User Stop hooks run only for root turns:
  - Thread-spawned subagents fire `SubagentStop`.
  - Internal subagents dispatch no hook at all.
  - Memory consolidation runs only managed hooks.
  
  Sources: `core/src/hook_runtime.rs` `run_turn_stop_hooks`, `stop.rs` `select_handlers`.
- Trust: `hooks/src/engine/discovery.rs` (`hook_trust_status`, handlers pushed only when Trusted or Managed),
  `tui/src/hooks_rpc.rs`, and `tui/src/startup_hooks_review.rs`.

**B. Legacy `notify`.** Add this to `~/.codex/config.toml`. There is only one `notify` slot, so this replaces any
existing notifier:

```toml
notify = ["python3", "/abs/path/to/moth-112m/code/moth/integrations/codex.py"]
```

- Codex appends `{"type":"agent-turn-complete", ..., "last-assistant-message": ...}` as the last argv argument and
  spawns the program with null stdio, without waiting for it (`hooks/src/legacy_notify.rs`).
- It is marked for removal ("TODO: Remove this hook ... when legacy `notify` support is removed").
- It is **not** gated by session source: `core/src/session/turn.rs` calls `run_legacy_after_agent_hook` for every
  turn. So subagent and memory-consolidation turns are probably posted too.
- Source: <https://github.com/openai/codex/tree/rust-v0.163.0/codex-rs>

## Hermes Agent

```bash
cp -r moth-112m/code/moth/integrations/hermes/moth ~/.hermes/plugins/moth
hermes plugins enable moth      # or add `moth` under plugins.enabled in ~/.hermes/config.yaml
```

- `post_llm_call` fires once per turn after the tool loop, with `assistant_response` set to the final text. It fires
  only on turns that produced a response and were not interrupted.
- `delegate_task` children run with `platform="subagent"` and are skipped.
- The POST runs on a daemon thread, so the hook returns at once.
- Sources: `website/docs/user-guide/features/hooks.md#post_llm_call` and
  `website/docs/developer-guide/plugins/index.md` in the Hermes repo. The firing site is
  `agent/turn_finalizer.py` `_apply_output_hooks`; the subagent platform is set in `tools/delegate_tool.py`.
  Checked against a local hermes-agent checkout at `c57331677d`, 2026-10-10.
- User plugins are opt-in (`plugins.enabled`).

## Pi

```bash
cp moth-112m/code/moth/integrations/pi/moth.ts ~/.pi/agent/extensions/moth.ts
# or for one run:  pi -e /abs/path/to/moth-112m/code/moth/integrations/pi/moth.ts
```

- `agent_end` (`messages` = the messages generated by that run) can be followed by retries, overflow recovery or
  queued work, so the adapter only remembers the last assistant text there.
- It posts on `agent_settled`, which means "Pi will not continue automatically", unless that event has `aborted`.
- `agent_start` clears the remembered text.
- Assistant messages with `stopReason` `error` or `aborted` are ignored. Only `text` blocks count.
- Sources: `docs/extensions.md`, `docs/json.md` and `docs/cli-integration.md` in the package, and
  <https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/extensions/types.ts>
  (`AgentStartEvent`, `AgentEndEvent`, `AgentSettledEvent`). Checked against main (v1.3.0) and the local 1.1.0
  `dist/core/extensions/types.d.ts`.
- Pi has no built-in subagents. Subagent extensions that spawn child `pi` processes will load this extension too,
  and those children will post.

## OpenCode

```bash
cp moth-112m/code/moth/integrations/opencode/moth.js ~/.config/opencode/plugins/moth.js     # global
# or: <project>/.opencode/plugins/moth.js
```

- Idle events carry only `sessionID`, so the adapter collects state from the event stream:
  - From `message.updated`, it records which message ids are assistant messages. Compaction (`summary`) messages
    are skipped; an `error` such as an abort means no reply.
  - From `message.part.updated`, it takes `text` parts that aren't `synthetic` or `ignored`. `part.text` is the
    full text, and the final update has `time.end`.
  - From `session.created` / `session.updated`, it treats sessions with an `info.parentID` as subagent (task tool)
    sessions and skips them.
- On `session.status` with `status.type === "idle"`, and on the deprecated `session.idle` fired at the same moment,
  it posts the newest assistant message's text and then forgets that session.
- Sources: <https://opencode.ai/docs/plugins/> (plugin dirs, `event` hook, `session.idle` / `session.status`), plus
  `packages/schema/src/session-status-event.ts` and `packages/schema/src/v1/session.ts` at tag `v1.19.3` in
  <https://github.com/anomalyco/opencode>, plus the local SDK types 1.2.10 (`@opencode-ai/sdk` `types.gen.d.ts`).

## dsh (DeepSeek Harness)

Add this to `~/.dsh/profiles/<profile>/cordis.patch.yml`, a YAML list, next to any existing entries:

```yaml
- insert: [{ id: moth, name: '/abs/path/to/moth-112m/code/moth/integrations/dsh/moth.mjs' }]
```

Or pass it for one run: `dsh --patch /path/to/patch.yml ...`, where the patch file holds the same list.

- `session/event` is the "post-commit, fire-and-forget append feed" of every session-log event. From it the adapter:
  - remembers the text blocks of the newest `assistant/message` in the turn, skipping `interrupted: true`;
  - on `turn/end` with `reason.kind` `completed` or `max-tokens`, posts that same turn's text;
  - posts nothing for aborted, error and blocked turns.
- Child sessions announced by `subagent/start` (`info.id`) are skipped.
- Sources: <https://github.com/deepseek-ai/deepseek-harness> `docs/subsystems/session.md` (`session/event`,
  `SessionEventMap`, `TurnEndReasonMap`), `docs/subsystems/subagent.md` and
  `packages/subagent/subagent/src/types.ts` (`SubagentRunInfo.id`), `packages/llm/llm/src/types.ts` (`TextBlock`).
  Checked at tags `dsh-v0.2.0-rc.2` (npm `latest`) and `dsh-v0.2.1-rc.2`. The `agent/turn-stopping` hook was not
  used because it can steer another step, while `turn/end` is the committed close.

## Updating

From `moth-112m/code`, with moth stopped: `python -m moth update --check` shows what changed (exit 10 = update
available), `python -m moth update` fetches only the changed files into the same folder, and `python -m moth update
--rollback` puts back the previous version. `python -m moth --version` prints the version and Hub revision. Hook
commands that point into `code/moth/integrations` keep working; re-copy any adapter you copied elsewhere (Pi
`moth.ts`, OpenCode `moth.js`, the Hermes plugin folder) when the update says integration files changed:
`python -m moth hooks` flags outdated copies and `python -m moth hook <harness>` replaces them. `~/.moth/`
(home, token) is never touched.

---

## Not verified live

All six adapters, the Claude Code band, the Pi widget and the OpenCode toast have since run live once, on
2026-10-18 (`../../video/raw/INDEX.md` in the dev checkout). That run found the `async` one-shot bug and the
cross-session display bug, both fixed since; the fixes were checked offline as described below, not in a new live run.
Each adapter is also checked with fake payloads shaped from the sources above (`test_integrations.py`):
- correct text posted;
- subagent, aborted and empty turns skipped;
- no output, exit 0;
- under 1.8 s against a moth that answers after 2 s;
- no crash with moth down or a bad URL.

Open points:
- **Session ids and labels** come from the payload fields in the table above, checked against sources (Claude Code
  docs, Codex `stop.rs` / `legacy_notify.rs` at `rust-v0.163.0`, Hermes `agent/turn_finalizer.py` and
  `agent/runtime_cwd.py` at c57331677d, Pi 1.1.0 `ExtensionContext` types, OpenCode SDK 1.2.10 `Session`), and only
  with fake payloads. dsh's session object was not checked for a cwd field, so its label is `process.cwd()`. Hermes
  in a messaging gateway without a configured cwd labels sessions with the gateway's launch folder.
- **Claude Code and Codex Stop**: if another Stop hook blocks and makes the agent keep going, the reply from before
  the block has already been posted, and the later reply posts too. An async observer can't tell them apart.
- **Pi**: a follow-up you queue mid-run runs before `agent_settled`, so only the last reply in that chain posts.
- **Claude Code / Codex Stop hooks** were run live on 2026-10-18 (Claude Code 2.1.302, Codex 0.163.0,
  `../../video/raw/INDEX.md` in the dev checkout): `async: true` posted from the interactive TUIs but not from
  `claude -p` / `codex exec`, so the hooks now run in the foreground.
- **Real CLIs, fake model** (`tests/e2e/`, `.github/workflows/e2e.yml`, GitHub-hosted Linux, macOS and Windows):
  `run_e2e.py` installs the hooks with `moth hook ... --yes` into a scratch home from a folder with a space (and
  again with a venv Python in a folder with a space), runs `claude -p` (2.1.302), `codex exec` (0.163.0), `pi -p`
  (1.3.0) and `opencode run` (newest) against a fake Anthropic / OpenAI API, and checks that serve.py's real handler
  got the final reply with the harness's own session id and the folder label, before the CLI exited. Codex's run
  uses `--dangerously-bypass-hook-trust`; a control run without it must post nothing (the unapproved hook is
  skipped). The approval itself was checked by hand in the interactive `codex` (`tui_live.py --tui codex`, Linux):
  the startup review's "trust" writes the `trusted_hash`, and `codex exec` then posts without the flag.
- **dsh**:
  - Not confirmed: whether a root-level `ctx.on('session/event')` receives events with no `inject`, and whether
    `session.id` equals `SubagentRunInfo.id` for in-process children.
  - Remote (`local: false`) subagents emit no local session events anyway.
- **OpenCode**:
  - Not confirmed live: that the assistant `message.updated` arrives before its idle event.
  - In one-shot `opencode run` / `pi -p`, the process may exit before the POST lands. In `tests/e2e` (one short
    reply, local fake model) both posted before exit on Linux, macOS and Windows; a slow machine may still lose it.
- **Pi**: child `pi` processes spawned by subagent extensions are not filtered.
- **Hermes**: in one-shot runs (`hermes -q`), the daemon thread can die at exit before posting.

Display layer: everything was checked against a stub moth with a real log (`Display` in `test_integrations.py`):
- `moth tail`: the watch output, wrapping, history, restart, chat echo, and "asleep" said once. Interactive
  redraw was checked by hand in a pty (libedit Python 3.14).
- Hermes registers no slash command.
- Pet `plugin.js` under node with a fake `ctx`: module shape, history skipped, the `moth` id, ttl bounds, 120-char
  pieces, moth down, and no `ctx.pet`.
- Pi widget and `/moth` with a fake `ctx.ui`.
- OpenCode toast with a fake `client.tui`. The event hook doesn't wait on the poll.
- Per-session displays: another harness's reaction landing last is not shown by the Pi widget, two OpenCode
  sessions in one process each get their own toast, the Hermes Desktop pet voices Hermes reactions only, and
  serve.py's `/api/says?source=&session=` filter (stripped answer, `next` unchanged, no ids leaked).
- The Claude Code band, live in the real interactive `claude` 2.1.302 (`tests/e2e/tui_live.py`, Linux, tmux, scratch
  home, fake model, serve.py's real handler): `$.session.id()` equals the Stop hook's `session_id` (the band polls
  `/api/says?...&session=<id>` every 2 s, the hook posts the same id), also after `/clear` (both switch to the new
  id, the old line is cleared). With this session's reaction shown, two decoys posted last (another session id; the
  same id under `source=codex`) don't replace it. The field: ctrl+x tab focuses it, Enter posts `/api/chat` with the
  token from `~/.moth/token` (`$.fs.read`) and shows the answer, no model request follows, and the field comes back
  empty.
- Pi's `/moth`: a reply slower than 4 s is picked up by an unfiltered poll (chat replies carry no session), so in
  that rare case another session's reaction could show instead.
- `show_in_harness`: off by default in Pi and OpenCode (the turn is still posted, no `/api/says` poll, no widget or
  toast; Pi's `/moth` answers with a notice); the env beating the file both ways; a live toggle on → off → on of the
  file in one Pi / OpenCode process (the widget is taken down, and turning it back on never shows a line from the off
  turn); Pi's reader and `moth/config.py` agreeing on every spelling. The `python -m moth config` CLI and the browser
  opt-in of `python -m moth` are in `tests/test_config.py`.
- `serve.py` on the real handler, with torch and the model faked out (`Serve`): the Host allow-list (look-alikes,
  a LAN IP, no port, no Host), the token on every guarded route, CORS (local pages everywhere, desktop-shell origins
  on `/api/says` only, look-alikes such as `localhost.evil.example` nowhere), foreign-origin / wrong-type / oversized
  / malformed POSTs, a bad `since`, `X-Frame-Options`, the token in the page but no CORS on it, `source` filtering, and
  "new home" refusing a folder without moth's marker.
- Every adapter sends the token and its `source`; the Claude Code hook posts past an `http_proxy` in its environment.
- Every adapter's `session` and `label` from fake payloads, end to end through the real handler and the real
  `Moth.hear_agent` onto the log's cards (`AdapterToLog`); their cleaning in serve.py (id charset, 40-char one-line
  label, ANSI stripped); the session list only in the token-guarded `/api/log`, never in `/api/says`; and
  `moth tail --session`.

Not verified:
- **Claude Code mod** (the rest was run live, see above): a click to focus the field; the band on macOS / Windows
  terminals; whether the poller survives a mid-session reload of the mod (it is started in `session.start`, and a
  reload drops timers).
- **Hermes Desktop**:
  - that the packaged renderer really sends `Origin: null`, or `file://`, both of which are allowed;
  - that the renderer's `fetch` to `http://127.0.0.1:4747` isn't blocked by a CSP or by Chromium's
    private-network rules. serve.py deliberately does not send `Access-Control-Allow-Private-Network`;
  - that the copied desktop half shows up in the Plugins page as described in `electron/desktop-plugins-root.ts`.
- **Pi**: how ANSI color looks inside a string-array widget. The interactive renderer wraps each string in a `Text`.
- **OpenCode**: that `client.tui.showToast` works from a plugin in 1.2.10 (the SDK types have it), and that
  `opencode run` exits promptly with the poll pending.
- **tail**: readline's redraw is called from the poll thread. It is cosmetic, but GNU readline was not tried.
- **Token reads inside harnesses**: checked (the Claude Code mod's `$.fs.read` of `~/.moth/token` live; Pi's and
  OpenCode's `node:fs` reads in `tests/e2e`, where moth refuses a post without the right token), but only with no
  other fs hook installed that might object.
- **Proxies in JS**: Node's `fetch` ignores `HTTP_PROXY`, but Bun's (OpenCode) honours it; with a proxy set and no
  `NO_PROXY=127.0.0.1`, OpenCode's posts may go to the proxy.