mirror of https://github.com/Ark0N/Codeman.git synced 2026-09-30 12:39:42 +02:00

Files

T

Codeman maintainer f3cb7696f0 docs: publish docs/wiki as the user manual, with a sync workflow

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>

2026-08-18 16:20:43 +02:00

5.1 KiB

Raw Blame History

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.

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. 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 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.

5.1 KiB Raw Blame History