HUG Agent

The hug agent implements human-in-the-loop review gates. When a pipeline reaches a type: gate phase with agent: hug, the agent assembles context from the workspace, creates a structured review on the HUG server, notifies reviewers, and polls for a verdict. The pipeline resumes based on the human’s decision.

The HUG agent can only be used on gate phases — it cannot be used as a standard phase agent. It requires a running HUG server and at least one configured reviewer.

For the full HUG system guide (server setup, reviewer configuration, notifications, examples), see Human Gate (HUG).

Sample Phase

- name: arch-review
  type: gate
  agent: hug
  depends_on: [architect]
  commands:
      - name: tests-pass
        run: npm test
  review:
      reviewer: tech-lead
      artifacts:
          - .cliq/design/architecture.md
      timeout: 8h

Phase Configuration

The HUG agent is used exclusively on type: gate phases. Review configuration is nested under the review: key.

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	Yes	Must be `"gate"`
`agent`	`string`	Yes	Must be `"hug"`
`role`	`string`	Yes	Role file providing review guidelines and context
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`commands`	`Command[]`	No	Pre-review validation commands — all must pass before review is created
`review`	`object`	Yes	Review configuration block (see Review Block Fields below)

Review Block Fields

Field	Type	Required	Default	Description
`reviewer`	`string \| string[]`	Yes	—	Named reviewer(s) from `hug.reviewers` in settings
`artifacts`	`string[]`	No	`[]`	Files or globs to include in the review context
`timeout`	`string`	No	`"24h"`	Auto-escalate duration (supports `s`, `m`, `h`, `d`)
`remind_every`	`string`	No	(none)	Re-notification interval — omit to notify once

Gate commands run first — all must pass before a review is created. Reviewers only see complete, valid work.

Verdict Mapping

Human Action	Gate Verdict	Pipeline Effect
Approve	`PASS`	Pipeline continues to next phase
Request Changes	`ROUTE:<target>`	Work routes to selected phase with feedback
Reject	`ESCALATE`	Pipeline halts — human intervention required
Timeout (no action)	`ESCALATE`	Pipeline halts with “timed out” reason

Settings

All settings live under the hug key in settings.json:

Key	Required	Default	Description
`hug.server_url`	Yes	—	URL of the HUG server
`hug.token`	No	—	User JWT (managed by `cliq hub login`)
`hug.enable_chat`	No	`false`	Enable chat assistant on the review page
`hug.enable_dynamic_review_ui`	No	`false`	Enable dynamic review UI rendering
`hug.max_artifact_size`	No	`50000`	Per-artifact character cap in LLM context
`hug.max_total_artifact_size`	No	`200000`	Total artifact character cap
`hug.llm`	No	—	LLM configuration for chat (provider, model, api_key)
`hug.reviewers`	No	`[]`	Named reviewer individuals and groups

Output

Handoff Structure

{
    "data": {
        "review_id": "rev-8f3a2b1c",
        "reviewer": "alice",
        "verdict_label": "approve",
        "comment": "Architecture looks solid. Caching strategy is well-reasoned."
    },
    "text": "Review rev-8f3a2b1c: approved by alice"
}

Field Reference

Field	Location	Description
`review_id`	`data.review_id`	Unique identifier for the review
`reviewer`	`data.reviewer`	Name of the reviewer who rendered the verdict
`verdict_label`	`data.verdict_label`	Human-readable verdict (`"approve"`, `"request_changes"`, `"reject"`, `"timeout"`)
`comment`	`data.comment`	Reviewer’s written feedback

Files Written

The HUG agent writes an audit trail to .cliq/reviews/{phase}-{review_id}.json containing the full review record — verdict, comments, timestamps, and reviewer identity.

Downstream Access

When routing (Request Changes), the reviewer’s comment becomes routing context delivered to the target phase through the gate channel.

commands:
    - name: show-verdict
      run: 'echo "Reviewed by $(handoff.code-review.data.reviewer): $(handoff.code-review.data.verdict_label)"'

Examples

Example: Code review after implementation

Standard review gate pattern — implement, validate, then get human approval.

phases:
    - name: implement
      agent: cursor

    - name: code-review
      type: gate
      agent: hug
      depends_on: [implement]
      commands:
          - name: tests
            run: npm test
          - name: lint
            run: npm run lint
      review:
          reviewer: [tech-lead, security]
          artifacts:
              - src/**/*.ts
          timeout: 8h
          remind_every: 2h

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [code-review]

Example: Single reviewer with short timeout

A lightweight review gate for low-risk changes.

phases:
    - name: implement
      agent: cursor

    - name: quick-review
      type: gate
      agent: hug
      depends_on: [implement]
      review:
          reviewer: team-lead
          artifacts:
              - "*.md"
          timeout: 2h

    - name: deploy
      agent: exec
      depends_on: [quick-review]
      commands:
          - name: publish
            run: npm publish

Example: Multi-stage review pipeline

Chain multiple review gates for high-compliance workflows.

phases:
    - name: implement
      agent: cursor

    - name: peer-review
      type: gate
      agent: hug
      depends_on: [implement]
      review:
          reviewer: peer
          artifacts:
              - src/**/*
          timeout: 4h

    - name: security-review
      type: gate
      agent: hug
      depends_on: [peer-review]
      review:
          reviewer: security-team
          artifacts:
              - src/**/*
              - package-lock.json
          timeout: 24h
          remind_every: 8h

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [security-review]

Setup

1. Start the HUG server

docker run -d --name hug-server \
  -p 3100:3100 \
  -e DATABASE_URL=postgres://user:pass@host:5432/hug \
  -e HUG_JWT_SECRET=$(openssl rand -hex 32) \
  -e HUG_ADMIN_KEY=$(openssl rand -hex 32) \
  ghcr.io/elanamir/hug-server:latest

See HUG Server for full installation options (npm, Docker Compose, local dev).

2. Configure credentials

If using CliqHub integration:

cliq hub login

For standalone servers, configure manually:

cliq settings hug.server_url http://localhost:3100 --global
echo '<jwt-token>' | cliq settings hug.token --stdin --global

3. Define reviewers

cliq settings --json hug.reviewers '[{"name":"alice","channels":["slack:alice"]},{"name":"bob","channels":["slack:bob"]}]' --global

4. Validate

cliq doctor

cliq doctor checks:

HUG server is reachable at hug.server_url
JWT token is valid (when configured)
LLM provider is accessible (when enable_chat is true)