mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-03 05:59:43 +02:00
Codeman maintainer
bd286bf502
The wiki was written for seven run modes and never received Grok Build, DeepSeek Harness or OMP. They now appear everywhere the others do: the modes table and per-CLI notes, install commands, environment prefixes, the Quick Start table, the requirements rows, the vocabulary, and every "seven modes" count. The 1.27 to 1.29.0 changes land on the pages that own them: attaching a case to an existing container, multi-case adoption and the copy-a-case picker (Docker Cases); file reads over ssh in remote cases and what stays unavailable (Remote SSH Sessions, Working With Files, Security); single-page app routing, frame recovery, localhost links as tabs and the egress guard (Web Tabs); DeepSeek as the one non-Claude mode with real stop/blocked signals and Approvals items, Codex's own work detection, last-response, the model-endpoint routes and refreshed counts (HTTP API, Driving From An Agent, Hooks, Notifications, Keeping Agents Running, Core Concepts); Shift+drag, right-click copy, Auto Copy, the Ctrl+Z guard, font weight, the vertical rail and its activity sort (Keyboard Shortcuts, Input And Voice, The Dashboard, Settings Reference); the 600px phone cutoff, Codex shift arrows and iPhone Duo (Mobile Guide); the Docker Compose route and its update rule (Installation, Running As A Service); four new symptom entries and a "which CLIs" question (Troubleshooting, FAQ). Custom model endpoints are deliberately left to #430, which adds that page and edits Agent CLIs, Settings Reference and the sidebar; these edits stay out of the regions #430, #428 and #376 touch, and all three still merge cleanly on top. Both READMEs: the web-tab menu entry is labelled "Add URL" in the UI, not "Add dashboard". Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
100 lines
5.3 KiB
Markdown
100 lines
5.3 KiB
Markdown
# 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](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](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](HTTP-API) and
|
|
[Driving Codeman From An Agent](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](https://github.com/Ark0N/Codeman/discussions/300), and if it needs a change
|
|
in Codeman to work properly, open an issue or a Discussion first.
|
|
|
|
## Read next
|
|
|
|
- [HTTP API](HTTP-API) - the endpoint map and envelope.
|
|
- [Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) - the agent-facing path.
|
|
- [`docs/extending-codeman.md`](https://github.com/Ark0N/Codeman/blob/master/docs/extending-codeman.md) - the seams in full, with examples.
|
|
- [`docs/claude-code-hooks-reference.md`](https://github.com/Ark0N/Codeman/blob/master/docs/claude-code-hooks-reference.md) - upstream hook semantics.
|