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.

Minimal configuration

{
  "hug": {
    "server_url": "http://localhost:3100",
    "token": "your-bearer-token"
  }
}

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	—	Bearer token for agent API authentication. Must match the server’s `--bearer-token`
`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)

Field	Type	Default	Description
`reviewer`	`string \| string[]`	(none)	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` in settings doesn’t match the server’s `--bearer-token`. They must be identical.
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 test slack` 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 `--bearer-token` — 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 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 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)