Hooks
Reference for Venom Full's guidance hooks in Claude Code and Codex, and how other clients get the same guidance without hooks.
Hooks add a short instruction to the agent’s context at key moments. They do not save work themselves. For the overall workflow, see How it works.
Where the guidance comes from.
Every connection receives Venom’s MCP server instructions when it starts: find and read the project and task before acting, create a task for new build work, log decisions, outcomes, and next steps, keep the status true, and check list_mentions.
The hooks ship in Venom Full (venom-full), a separate plugin for Claude Code and Codex. The venom plugin ships no hooks, because Anthropic’s and OpenAI’s plugin directories don’t accept hooks from us. Venom Full installs from the same marketplace and uses the venom plugin’s connection, so there’s one sign-in and one set of Venom tools.
Venom Full’s hooks are mcp_tool hooks. Each one calls Venom’s get_guidance tool with the event name over the existing MCP connection, so the wording lives on the server and changes without a plugin update. No local script runs, so neither client needs Node.js.
Without Venom Full, Claude and Codex get their guidance from the venom skill, the server instructions, and a one-line reminder at the top of every Venom tool response. The skill also tells the agent to log what changed before its final reply. Any client without hooks gets the same tool-response reminders. While Venom Full’s hooks are active, the server stops adding those reminder lines.
In Claude Code and Codex with Venom Full, the agent is shown your projects and unread mentions on the first prompt of a session. When a turn reached a milestone and nothing was logged to Venom, it is asked once to log what changed. Other clients get their guidance from the server’s instructions and the reminder lines in tool responses.
Events.
| Event | Guidance |
|---|---|
UserPromptSubmit | On the first prompt of a session, your Venom projects and unread mentions. After that, new mentions only. Adds nothing when there are none. |
SessionStart (after compaction) | Re-read the current Venom task and log decisions from before compaction that aren’t saved yet. |
PreCompact | Keep the Venom project and task, unlogged decisions, and unanswered mentions in the compaction summary. Claude Code only. |
SubagentStart | Read Venom if it helps, but return findings to the parent agent unless given a Venom task to own. |
PostToolUse | After a commit, push, pull request, merge, release, closed issue, workflow run, deploy, or publish, log the outcome to the task if it advances one. |
Stop | If the turn reached one of those milestones and nothing was logged to Venom after it, ask once more. The agent logs only if there’s something worth recording. |
Launch guidance comes from the server instructions, so SessionStart only matches compaction, and projects and mentions arrive with the first prompt. get_guidance returns nothing when there is nothing worth adding.
Host setup.
| Client | Bundled events | Setup |
|---|---|---|
| Claude Code | All of the above | Install Venom Full. Claude Code installs venom with it. |
| Codex | All of the above except PreCompact | Install both plugins (see the Quickstart), enable lifecycle hooks in your Codex configuration, and trust the Venom hooks once in /hooks. Codex PreCompact can’t add context, so it isn’t registered. |
| Claude chat and Cowork | None | Add the venom plugin from the plugin directory. Guidance comes from the venom skill and tool responses. |
| Gemini CLI | None | Install the extension folder from the plugin repository. Its context file loads in every session. |
Other adapters use client rules or instruction files. See the plugin’s setup and coverage notes for the differences between hosts.
Controls and failures.
Your client still controls sign-in and tool approvals. Disabled skills stay disabled. Turning off hooks or removing Venom Full stops the hook reminders; it does not revoke an otherwise configured MCP connection.
Hooks use the existing connection and never start sign-in. If Venom isn’t connected, the hooks do nothing and don’t block the session, and the agent still has the server instructions once it connects. A failed or interrupted save can leave work unsaved. Agents are instructed to report that and include the missing context in their handoff.
Upgrade notes.
Version 0.8.0 adds Venom Full to the marketplace; the hooks now live there. Version 0.7.0 removes the Codex plugin’s hooks: install Venom Full to get them back, and remove the old Venom hooks from /hooks. Version 0.6.0 removes the Claude plugin’s hooks and adds the venom skill. Versions before 0.5.0 told agents to load an organization session-start skill and ran a local Node.js script for these events. Venom no longer creates that skill. Update the plugins and start a fresh session.