Hooks And Integrations

Hooks and Integrations

Events flowing back into Codeman, and the four seams a third party can build against.

Hooks

Claude Code can run a command when something happens in a session. Codeman writes a hooks configuration into each Claude case so those events post back to it, which is what turns a terminal into something that can notify you.

Event	Fires when	Drives
permission_prompt	The agent asks for permission.	Red tab alert, Approvals Inbox, push.
idle_prompt	The agent is waiting for input.	Yellow tab alert, the idle wait signal.
stop	A turn ends.	The stop wait signal, idle detection.
elicitation_dialog	A dialog opens.	Approvals Inbox.
elicitation_complete	The dialog closes.	Clearing the alert.
elicitation_response	The dialog is answered.	Clearing the alert.
teammate_idle	An agent-team member goes idle.	Team surfaces.
task_completed	A task finishes.	Task tracking, run summary.

This is why several Codeman features are Claude-only. The one partial exception is DeepSeek Harness, whose terminal front door reports idle, working and blocked to Codeman over the harness's own supervisor contract, so it gets the hook-driven surfaces without any hook file. The other CLIs have no equivalent, so for them Codeman watches terminal output, which reveals that something happened but not what it was.

How hooks get installed

Codeman writes them into the case when a Claude session is created. Hook blocks are marker-owned: Codeman only ever updates a block it wrote, and never touches configuration you added yourself.

If tab alerts and approvals never fire in a particular case, that case is missing its hook block. Recreating the case rewrites it.

The hook secret

/api/hook-event and /api/status-telemetry skip HTTP Basic authentication, because they are called from localhost by the CLI itself. When authentication is on, that bypass additionally requires a per-instance hook secret, because Codeman cannot tell a genuine loopback call from a request arriving through your own loopback reverse proxy.

The secret lives in the data directory, and its path is exported into every managed session.

Two things that break hooks

• HTTPS. Hook callbacks must accept the self-signed certificate. Recent versions self-heal existing cases; older cases need recreating.
• Docker cases on a loopback bind. A container cannot reach 127.0.0.1 on the host, so in-container hooks silently do not fire. Set CODEMAN_DOCKER_BRIDGE_HOOKS=1 to open a hooks-only listener on the bridge gateway. See Docker Cases.

Integration seams

Codeman has no plugin runtime, and that is a decision rather than a gap. A plugin runtime means running third-party code inside a process that spawns agents with your credentials, on a server people routinely expose over a tunnel. Codeman's security posture is one of its reasons to exist, so it does not trade that away for an extension mechanism.

What exists instead is four documented seams.

1. Web tabs

Anything with a web UI can live inside Codeman as a tab, proxied through Codeman's own origin. The lowest-effort integration by a wide margin: if your tool has a dashboard, it can sit beside the agents with no code at all. See Web Tabs.

2. SSE events

GET /api/events streams everything Codeman knows: session lifecycle, output, agent activity, approvals, cron runs. 158 named events, stable under semantic versioning.

This is the seam for anything that reacts. A bot that pings your chat channel when an agent needs a human is a short script over this stream.

3. HTTP API and CLI

Everything the dashboard does. Create sessions, send input, block on wait primitives, read terminals, manage cron. See HTTP API and Driving Codeman From An Agent.

4. Hooks

The seam above, in the other direction: your own hook commands can run alongside Codeman's in a case, as long as you leave Codeman's marker-owned block alone.

Publishing an integration

There is no registry to submit to. Share it in Show and tell, and if it needs a change in Codeman to work properly, open an issue or a Discussion first.

Read next

• HTTP API - the endpoint map and envelope.
• Driving Codeman From An Agent - the agent-facing path.
• docs/extending-codeman.md - the seams in full, with examples.
• docs/claude-code-hooks-reference.md - upstream hook semantics.