cware-hil-mcp

Human-in-the-loop MCP hub for Claude Code agents, answered in Obsidian.

Agents call MCP tools to ask a human a question, request approval, or report status. This standalone hub holds the queue and exposes an MCP endpoint; the Obsidian plugin is the human's UI.

Claude Code agents ──HTTP /mcp──▶  hub (Go, :22360)  ◀──ws /bridge──  Obsidian plugin
                                   └ SQLite queue (survives restarts)

The hub is written in Go (single static binary, pure-Go SQLite — no cgo). Shared domain types + the bridge protocol live in cware-hil-lib: its zod schemas are the single source of truth, emitted as JSON Schema and code-generated into internal/protocol/domain.gen.go, so a shape change in the lib is a Go compile error here. Run go generate ./... to regenerate after a lib change.

Build

go build -o cc-hitl ./cmd/hub

Requires Go ≥ 1.26. No native toolchain needed — modernc.org/sqlite is pure Go, so CGO_ENABLED=0 produces a fully static binary.

Related MCP server: Herald

Run

./cc-hitl start            # start the hub
./cc-hitl status           # health check
./cc-hitl stop             # stop the running hub
./cc-hitl token            # print the bearer token
./cc-hitl setup            # print Claude Code / Obsidian connection details

State lives in ~/.cc-hitl/ (hub.json holds the token; hub.db is the queue). The hub binds to 127.0.0.1 by default; override with --host <addr> or CC_HITL_HOST (e.g. 0.0.0.0 to accept connections from other machines).

This container serves no UI — only /mcp, /bridge, and /health (and a plain pointer at /). The web UI is a separate deployable, cware-hil-ui, that you point at this hub for a setup page + live dashboard. The CLI also prints the connection snippets on start (and via cc-hitl setup).

Docker

export CC_HITL_TOKEN=$(openssl rand -hex 24)
docker compose up -d --build
docker compose exec hub /cc-hitl status

The container binds 0.0.0.0 and compose publishes it on 127.0.0.1:22360. State persists in the hub-data volume (CC_HITL_HOME=/data). The image is a distroless static build (~24 MB). Without compose:

docker build -t cware-hil-mcp .
docker run -d --name cc-hitl -p 127.0.0.1:22360:22360 \
  -e CC_HITL_TOKEN=$CC_HITL_TOKEN -v cc-hitl-data:/data cware-hil-mcp

Exposing beyond loopback: once published on a LAN/public interface, the bearer token is the only thing protecting /mcp and /bridge. Use a strong CC_HITL_TOKEN and put a TLS reverse proxy in front.

Prebuilt images

CI publishes images to GitHub Container Registry on every push to main:

docker pull ghcr.io/kiliansen/cware-hil-mcp:latest      # newest build
docker pull ghcr.io/kiliansen/cware-hil-mcp:0.1         # latest 0.1.x
docker pull ghcr.io/kiliansen/cware-hil-mcp:0.1.1       # exact version

Versioning is driven by commit messages (Conventional Commits): fix: bumps the patch, feat: the minor, and feat!: / a BREAKING CHANGE: footer the major. A commit with no conventional prefix bumps the patch. Each push tags the repo (vX.Y.Z) and pushes matching X.Y.Z, X.Y, X, and latest image tags. See .github/workflows/docker.yml.

Connect Claude Code

cc-hitl start prints the exact command (or use the cware-hil-ui setup page). In your project:

claude mcp add --transport http --scope project hitl http://127.0.0.1:22360/mcp \
  --header "Authorization: Bearer <token>"

Set a long per-server timeout (the printed snippet uses 24h) because the ask tools block until a human answers.

Tools agents get

• ask_user(prompt, title?, agent_label?, agent_key?) — open question, returns typed text. Blocks.

• ask_choice(prompt, choices[], multi?, …) — pick one/several (+ optional note). Blocks.

• request_approval(title, body, diff?) — approve/reject + comment. Blocks.

• notify(message, level?) — fire-and-forget notice. Non-blocking.

• update_status(label?, status?, current_task?, progress?, done?) — dashboard feed. Non-blocking.

• check_messages(agent_key?) — receive messages the human sent you. Non-blocking.

• unregister_agent(agent_key?) — drop this agent from the dashboard. Non-blocking.

Test

go test ./...

The internal/e2e suite spawns a real hub on a temp CC_HITL_HOME and drives each tool through an MCP client + bridge WebSocket client; internal/hub covers cancellation, timeout, orphaned-answer delivery, persistence across restart, and the stale-agent sweep.