HUG Settings & Troubleshooting

Settings Reference

All HUG settings live under the hug key in settings.json. Settings merge like all cliq settings — define the server URL and token globally in ~/.cliqrc/settings.json, override reviewers or chat config per-project in .cliq/settings.json if needed.

The server_url and token fields are automatically managed by cliq hub login when the HUG server is integrated with CliqHub. You typically only edit reviewers, chat, and LLM settings by hand.

Minimal configuration

{
  "hug": {
    "server_url": "https://hug.example.com",
    "token": "<user-jwt-managed-by-cliq-hub-login>"
  }
}

Full configuration

{
  "hug": {
    "server_url": "https://hug.example.com",
    "token": "hug-auth-token",
    "enable_chat": true,
    "llm": {
      "provider": "anthropic",
      "model": "claude-haiku"
    },
    "reviewers": [
      { "name": "alice", "channels": ["slack:alice", "email:[email protected]"] },
      { "name": "bob", "channels": ["slack:bob"] },
      { "name": "carol", "channels": ["slack:carol"] },
      { "name": "architects", "members": ["alice", "bob"], "policy": "any" },
      { "name": "security", "members": ["carol"], "policy": "any" }
    ]
  }
}

Reviewer model

Reviewer entries come in two shapes:

Individuals have channels — notification routes for one person. Define a person’s channels once, reference them by name from any number of groups.
Groups have members — a list of individuals or other groups, plus a policy that governs how approvals are evaluated.

With policy: "any" (the only supported policy today), all members are notified and the first person to submit a verdict decides the outcome of the gate. Groups are a configuration convenience — they let you organize individuals and avoid duplicating channel definitions when the same person appears in multiple review contexts.

When a workflow references reviewer: [architects, security], all individuals across all named groups are notified, and one verdict from anyone resolves the gate.

Field reference

Field	Type	Required	Default	Description
`server_url`	`string`	yes	—	URL of the hug server
`token`	`string`	no	—	User JWT for hug server authentication. Managed automatically by `cliq hub login`
`enable_dynamic_review_ui`	`boolean`	no	`false`	Reserved for future use
`reviewers`	`array`	no	`[]`	Named reviewer individuals and groups. Referenced by name in `team.yml`
`reviewers[].name`	`string`	yes	—	Unique name, referenced in `review.reviewer` or in group `members`
`reviewers[].channels`	`string[]`	individual	—	Notification routes for an individual. See channel format
`reviewers[].members`	`string[]`	group	—	Names of individuals or other groups that belong to this group
`reviewers[].policy`	`string`	no	`"any"`	Approval policy (groups only). Currently only `"any"` is supported (first reviewer to submit decides)
`enable_chat`	`boolean`	no	`false`	Enable the chat panel on the review page. When `false` or omitted, the review page shows “Chat is not enabled for this review”
`llm`	`object`	when `enable_chat` is true	—	LLM provider configuration for the chat assistant
`llm.provider`	`string`	yes (when llm needed)	—	LLM provider: `"anthropic"`, `"openai"`, or `"google"`
`llm.model`	`string`	no	Provider default	Model name (e.g., `"claude-haiku"`, `"gpt-4o-mini"`, `"gemini-2.0-flash"`). Uses the provider’s default model when omitted
`llm.api_key`	`string`	no	—	API key override. When omitted, falls back to the provider’s env var (`GOOGLE_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
`max_artifact_size`	`number`	no	`50000`	Per-artifact character cap when passing artifact content to LLM context (verdict generation and chat assistant). Artifacts exceeding this limit are truncated
`max_total_artifact_size`	`number`	no	`200000`	Total character cap across all artifacts in LLM context. Once reached, remaining artifacts are omitted with a note

LLM provider defaults

Provider	API key env var	Default model
`anthropic`	`ANTHROPIC_API_KEY`	`claude-sonnet-4-20250514`
`openai`	`OPENAI_API_KEY`	`gpt-4o-mini`
`google`	`GOOGLE_API_KEY` or `GEMINI_API_KEY`	`gemini-2.0-flash`

`review:` block reference (team.yml)

Nested under a gate phase with agent: hug:

- name: my-review
  type: gate
  agent: hug
  review:
      reviewer: ...
      artifacts: [...]
      timeout: "8h"
      remind_every: "2h"

Field	Type	Default	Description
`reviewer`	`string \| string[]`	(required)	Named reviewer(s) from `hug.reviewers`
`artifacts`	`string[]`	`[]`	Files or globs to include. Expanded at runtime
`timeout`	`string`	`"24h"`	Auto-escalate duration. Supports `s`, `m`, `h`, `d`
`remind_every`	`string`	(none)	Re-notification interval

Troubleshooting

Issue	Fix
”hug.server_url is required in settings.json when using human gates”	`cliq assemble` throws a hard error when a team uses human gates but `hug.server_url` is missing. Add `hug.server_url` to your settings. See Connecting cliq to the server.
Review creation fails with “Unauthorized”	The `hug.token` JWT has expired or is invalid. Run `cliq hub login` to refresh it.
Reviewer never got a Slack notification	Check that the reviewer name in `team.yml` matches a name in `hug.reviewers`, and that their channel resolves to a valid Slack webhook. Run `cliq doctor` to verify.
Chat shows “Chat is not enabled for this review”	Chat is disabled by default. Set `hug.enable_chat` to `true` and configure `hug.llm.provider` in settings.
”hug.llm.provider is required when enable_chat is true”	When chat is enabled, you must specify a provider. Set `hug.llm.provider` to `"anthropic"`, `"openai"`, or `"google"`.
”No API key for hug LLM provider…”	Set `hug.llm.api_key` in settings or export the provider’s env var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY` / `GEMINI_API_KEY`).
Chat shows “Thinking…” indefinitely	Verify the hug server was started with `--jwt-secret` — without it, the agent’s WebSocket connection isn’t authenticated and messages aren’t relayed. Also check that the API key for the configured `hug.llm.provider` is valid and the model is accessible.
Review page shows “This review has expired”	The timeout elapsed before the reviewer acted. Increase `timeout` in the `review` block, or add `remind_every` to send reminders.
”Phase ‘X’ references reviewer ‘Y’ but no reviewer with that name…”	The name in `review.reviewer` doesn’t match any entry in `hug.reviewers`. Check spelling and add the reviewer to settings.
Hug server won’t start (ECONNREFUSED on Postgres)	Verify the PostgreSQL connection string — host, port, username, password, and database name. If using Docker Postgres, the container’s internal port (5432) may map to a different host port.
Verdict submitted but pipeline didn’t continue	The hug agent may have timed out before the verdict was submitted. The agent and server enforce timeouts independently — if the agent’s deadline passes, it returns `ESCALATE` regardless of what’s on the server. Check the `timeout` value.

Validation

`cliq assemble`

Hard error if hug.server_url is missing for any team that uses agent: hug phases. This is not a warning — assembly fails.
Verifies that review.reviewer names exist in hug.reviewers in settings.
Verifies that the review: block only appears on agent: hug phases.
When enable_chat is true, validates that hug.llm.provider is set and an API key is available (hug.llm.api_key or env var).

`cliq doctor`

Checks hug server reachability when hug.server_url is configured.
When enable_chat is true, verifies:
- hug.llm.provider is set to a valid provider ("anthropic", "openai", or "google")
- An API key is available (in hug.llm.api_key or the provider’s env var)