mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-03 14:09:42 +02:00
Codeman maintainer
f3cb7696f0
30 pages covering install, concepts, the dashboard, the agent CLIs, unattended
runs, remote and Docker cases, security and the HTTP API, plus a sidebar and a
footer. The wiki repo has no CI and no review, so docs/wiki is the source of
truth and .github/workflows/wiki-sync.yml mirrors it on every push to master.
The workflow refuses to mirror when docs/wiki is missing or holds no pages,
because it deletes before it copies and would otherwise publish the deletion of
every page. The footer carries a {{VERSION}} placeholder stamped at publish
time rather than a hand-written version, which went stale on every release.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
98 lines
5.1 KiB
Markdown
98 lines
5.1 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 other CLIs have no hook system, 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. 155 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.
|