agent-integrations
Skill0 starsChanged 43 days agoMITView on GitHub
Verified facts (as of 2026-10-01) for pushing and pulling context with Claude Code, Codex, OpenCode, and tmux - hook JSON shapes and limits, MCP registration syntax, OpenCode's HTTP server endpoints, tmux bracketed-paste delivery, and what each agent does with image paths. Read before writing any transport other than Herdr, the hook installers, or the MCP server's tool surface.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- buildSkill
- context-packetSkill
- herdr-apiSkill
- run-appSkill
- sftp-over-sshSkill
- verify-transportSkill
The file
Files
Agent integrations
Gloss installs no hooks (since 2026-10-05, issue #5): a UserPromptSubmit hook fires on every prompt, including the one a Herdr or tmux send submits, so it cannot tell "the user chose these" from "a prompt happened". Drafts leave only on Send; agents read and resolve sent notes through MCP. The hook facts below stay for reference (and for removing the old entry, gloss-notes.sh).
Everything below was checked against the live docs or binaries on this machine. Re-verify before relying on anything marked "unverified".
Claude Code
- UserPromptSubmit hook (pull): script on stdin gets
{session_id, cwd, hook_event_name, prompt, ...}. Inject context by printing JSON:
Limit 10,000 characters per field. Also works for{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"<text>"}}SessionStart. Plain stdout (non-JSON) is added as context too, but use the JSON form. - Hook install location:
~/.claude/settings.json→hooks.UserPromptSubmit[].hooks[]. MERGE with existing entries (Herdr's integration writes aSessionStarthook and amoshi-hookentry already sits onUserPromptSubmit). Handler fields:type,command,timeout,async. Over the 10,000-char cap Claude Code writes the context to a file and substitutes a path plus a 2,000-char preview. Script lives at~/.claude/hooks/gloss-notes.sh. - MCP over HTTP:
claude mcp add --transport http gloss http://127.0.0.1:<port>/mcp(user scope with-s user). Equivalent.mcp.jsonentry:{"mcpServers":{"gloss":{"type":"http","url":"http://127.0.0.1:<port>/mcp"}}}. - Images: a prompt that names an absolute image path works; Claude Code reads PNG/JPEG via its Read tool and sees the pixels.
- No external turn injection into a live interactive session. Push goes through Herdr or tmux only.
- Session UUIDs are available from Herdr's
agent_sessionwhen the Herdr integration is installed.
Codex
- Hooks are experimental:
~/.codex/hooks.json(or[hooks]in~/.codex/config.toml) and[features] hooks = truemust be set. Events includeSessionStartandUserPromptSubmit(since v0.116). Output shape mirrors Claude Code:
Plain stdout is also added as developer context. Docs: https://learn.chatgpt.com/docs/hooks{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"<text>"}} - MCP:
codex mcp add gloss --url http://127.0.0.1:<port>/mcp(verified againstcodex mcp add --help, Codex 0.157.0). - Trust: Codex skips new or changed hooks until the user trusts them with
/hooksinside Codex (stored as[hooks.state."<file>:user_prompt_submit:<i>:<j>"] trusted_hashinconfig.toml). The installer must say so.[features] hooks = trueis already set on this Mac. - Images:
codex -i <file>attaches images only at launch. Whether Codex reads an image path mid-session through a tool is unverified; the packet still carries the path and coordinates, and MCP exposes the crop as a resource.
OpenCode
opencodeTUI starts an HTTP server on a random port.opencode --port 4096(oropencode serve --port 4096headless) fixes it. The TUI's own server answers every outside request with403 forbidden(verified 2026-10-04 on 1.18.31);opencode serveanswersGET /sessionwith 200. Gloss finds servers itself:lsof -nP -a -iTCP -sTCP:LISTEN -c '/opencode/' -F nlists every OpenCode listener on any port, and the transport keeps those whoseGET /sessionsucceeds, so there is no setting. Default host 127.0.0.1. Optional basic auth viaOPENCODE_SERVER_PASSWORD.- Endpoints (verified against the SDK types, OpenCode 1.18.31):
GET /session?directory=lists sessions{id, projectID, directory, title, time{created,updated}};POST /session {parentID?, title?}creates one;POST /session/:id/messagewith{parts:[{type:"text",text:"..."},{type:"file",mime:"image/png",url:"file:///abs/path.png",filename?:"..."}]}sends a turn and waits;POST /session/:id/prompt_asynctakes the same body and returns 204 immediately (use this one). Basic auth:OPENCODE_SERVER_PASSWORDwith userOPENCODE_SERVER_USERNAME(defaultopencode). OpenAPI athttp://localhost:4096/docwhen a server is running. - Plugins (
~/.config/opencode/plugins/*.js) cannot inject AI-visible messages yet (open issues #17412, #22831). Do not build on them. - MCP:
~/.config/opencode/opencode.json→"mcp":{"gloss":{"type":"remote","url":"http://127.0.0.1:<port>/mcp","enabled":true}}(verified against the docs), oropencode mcp add gloss --url <url>.
tmux (no Herdr)
Deliver with bracketed paste so multi-line packets do not submit early:
tmux load-buffer -b gloss - # packet on stdin
tmux paste-buffer -p -b gloss -t <target> # -p = bracketed paste
tmux send-keys -t <target> Enter
tmux delete-buffer -b ccOver SSH run the same through the exec channel; pipe the packet into ssh <host> tmux load-buffer -b gloss -. Discover panes with tmux list-panes -a -F '#{pane_id}\t#{session_name}:#{window_index}.#{pane_index}\t#{pane_current_command}\t#{pane_current_path}' and let the user pick once per host; store the session:window.pane name in target for display and send to pane_id (%12): closing and renumbering windows hands a session:window.pane to another pane, while a pane id stays with its pane for the server's life. Agent panes usually show node (Claude Code), codex, or opencode as the current command.
Shared MCP server surface (what every agent sees)
Tools (agents see sent notes only; drafts never): list_pending_notes(host?, path?), get_note(id), resolve_note(id, outcome?, message?, location?), reply_to_note(id, message, asks?, location?) (a reply, or a question that leaves the note waiting on the user; see the context-packet skill for location), list_documents(), open_in_viewer(path|url, line?, end_line?, host?), ask_user(path, question, line?, end_line?, text?, host?) (a sent note with author = the client's agent name, no comment, and the question as its first message, waiting on the user; at most 20 open per document), add_favorite(path, host?), list_favorites() (host defaults to the session's: a remote registration URL is http://127.0.0.1:<port>/mcp?host=<alias>, quoted in the mcp add shell line). Resources: note://<id>/attachment/<n> serving image/png. Keep tool names stable; the packet's closing line names resolve_note literally.
Every route but /health needs the server's token (Authorization: Bearer <token> or token=<token> in the query): the registration URL carries ?token=… (and &host=<alias> remotely), and the port file (mcp-port, 0600; ~/.config/gloss/mcp-port on a host) holds the port on line 1 and the token on line 2 for the hook script and the Herdr plugin. GET /hook/claude and /hook/codex return the drafts under cwd (and host) in the UserPromptSubmit JSON shape; GET /hook/text returns the same packet as text/plain for any other agent's prompt hook (Settings → Agents → Other agents gives the curl line). All three drain what they return to sent (recorded as claude-hook, codex-hook, prompt-hook) and answer an empty 200 when there is nothing. The token lives in ~/Library/Application Support/Gloss/mcp-token. Without it anyone else logged in to a host could reach the forwarded port and read the notes. Requests with an Origin or a non-loopback Host are refused too.
Remote agents reach the server through a reverse forward on the app's SSH control connection: ssh -O forward -R <port>:127.0.0.1:<port> <host>. Use the same port number on both ends so the agent config is identical everywhere.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

