jcode-herdr

A community hook that registers jcode sessions in herdr's agents view, with session identity for restore.

Every jcode session started inside a herdr pane reports its native session id plus best-effort working / idle / blocked lifecycle. Panes show up in herdr's agents sidebar with live status, carry the session id as a token for manual jcode --resume <id>, and will support automatic restore once herdr accepts jcode as an official session source.

Install

mkdir -p ~/.jcode/hooks
curl -o ~/.jcode/hooks/herdr-agent-state.sh \
  https://raw.githubusercontent.com/joeharris76/jcode-herdr/main/herdr-agent-state.sh
chmod +x ~/.jcode/hooks/herdr-agent-state.sh

Then add to ~/.jcode/config.toml:

[hooks]
session_start = "~/.jcode/hooks/herdr-agent-state.sh"
turn_end = "~/.jcode/hooks/herdr-agent-state.sh"
session_end = "~/.jcode/hooks/herdr-agent-state.sh"
pre_tool = "~/.jcode/hooks/herdr-agent-state.sh"
post_tool = "~/.jcode/hooks/herdr-agent-state.sh"

Or run ./install.sh from this repo, which copies the hook and appends the config entries (skipping any already set). jcode picks up hook changes live; no restart needed.

Verify: start a session in a herdr pane, then check herdr agent list for an agent jcode entry.

What it sends

Per event, newline-delimited JSON to HERDR_SOCKET_PATH:

1. pane.report_agent_session (source "herdr:jcode") — native session identity. Forward-compatible: herdr 0.9.0 accepts but does not persist unofficial sources, so this takes effect once upstream support lands.
2. pane.report_metadata (source "user:jcode-session") — durable jcode_session token for labeling and manual resume. Display-only.
3. pane.report_agent (source "custom:jcode") — lifecycle state. This is what registers the pane in the agents view. The custom: namespace keeps it collision-free with a future official integration.

Mapping: session_start / turn_end → idle; pre_tool → working; post_tool → idle (or blocked on error, as an attention hint); session_end → idle. States are transition signals, not full lifecycle authority — true permission/question blocking needs explicit jcode events that do not exist yet.

Safety

• No-op outside herdr (exits 0 silently). Observer hooks are detached; the synchronous pre_tool gate always exits 0 with no stderr, so it can never block or fail a tool call.
• Sends socket messages only. Never sends input to panes, never shells out.
• Per-pane monotonic sequence numbers survive clock skew and concurrency.
• Temporarily disable without editing config: JCODE_HOOK_SESSION_START="" jcode ...

Limitations

• herdr 0.9.0 persists no session reference for unofficial sources, so automatic restore awaits upstream work. Manual jcode --resume <id> from the token works today.
• Headless swarm workers may label the daemon's birth pane; harmless and self-healing (overwritten by the next real session there).

Upstream

First-class jcode support needs herdr-side changes: accept ("herdr:jcode", "jcode") as an official session source, persist the session reference, map it to jcode --resume <id>, and add process detection plus a screen manifest. See the jcode Herdr integration contract for the full prescription.

License

MIT. Requires sh, python3, jcode, and herdr.