> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hugs overview

> What a hug is, who does what, and when you need your own instead of form or approval.

Hugs

A **Hug** is a request a run makes of people ([Asking people](https://docs.getcliq.io/hugs.md)). A **hug** is the page they answer it on: a small
web frontend, plus a **definition** of what it is asked (its **params**) and what a valid answer is (its **values**).
Every Hug is asked with one.

Two hugs ship with cliq: **`form`** (fields to fill in) and **`approval`** (approve or reject, the review gate's).
When a page made for the job would be clearer than a form — triage a list, review a batch of documents with a verdict
each, compare two versions, sign off a checklist with evidence — you write your own.

> [!TIP]
>
> **Try `form` first.** If the ask is "fill in these fields" or "approve or reject", `form` and `approval` already do it —
> `ctx.ask(form, { params: { inputs } })` in agent code, or nothing at all in an LLM phase.

***

## What a hug is

A folder named for the hug. You write the definition and the page; `cliq hug build` writes the bundle to `dist/`:

```text theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
review-batch/                 the hug — its name is the folder's name
  hug.ts                      define_hug: params, values, summary — imported by the page and by agents
  src/main.ts                 mount_hug: the page
  hug.test.ts                 tests of the definition
  package.json, build.mjs
  dist/                       the bundle: what cliqd serves and CliqHub shows
    hug.json                  generated: name, title, description, entry, SDK version
    definition.mjs            generated: the definition, for agents and models
    index.html, assets/…      the page, with every library compiled in
```

* **One definition, two checks.** The page runs the definition on every change, so the person sees what's wrong and
  Submit stays disabled until the answer is valid. The agent runs it again on every answer before acting on it — the
  check that counts, because a browser can't be trusted.
* **The bundle is self-contained text**: every library compiled in, binary assets inlined, at most 5 MB and 200 files.
  It has no network: the data it shows arrives as params and attached files.
* **An installed hug needs only `dist/`.** The source is for development.

***

## Who does what

| | Who | Where |
| - | - | - |
| What the Hug shows, and checking the answer for the person | the hug's author | the page (`mount_hug`) |
| Checking the answer for real | automatic, from the definition | the agent (`ctx.ask`) |
| Which hug a phase asks with | the team's author | `team.yml` — a phase's `hug: { name }` — or agent code |
| When the answers are enough (policy) | the agent | `ctx.ask`'s `policy` |
| Finding a hug by name | cliqd | the team, `CLIQ_HUGS_PATH`, `~/.cliqrc/hugs` ([Installing](https://docs.getcliq.io/hugs/installing.md)) |
| Who may answer; expiry, reminders, files | CliqHub | as for every Hug |
| Showing the page safely | CliqHub and cliqd | a sandboxed frame on a separate content host ([Security](#security)) |
| Title, who asked, the run, expiry, the **Submit** button | the Hub page | around the frame |

***

## The page's states

The Hub (or cliqd's local page) decides what the person sees; a hug draws only two things — an answer to **edit** and
an answer to **view**:

| State | The hug draws | Around it |
| - | - | - |
| Open; you may answer and haven't | **edit**, from your draft or empty | **Submit**, with the label the hug chooses |
| Open; you've answered | **view** of your answer | "Submitted 10:42 · **Change answer**" |
| Changing your answer | **edit**, from your answer | Submit and Cancel |
| Open; you may see it but it wasn't sent to you | each response, in **view** | "Only people this Hug was sent to can answer it" |
| Ended (closed, expired, cancelled) | each response, in **view** | how it ended |

Each response also carries a one-line **summary** from the definition ("2 of 3 OK", "Approved"), shown in the
inbox, notifications and "Alice responded: Approved".

***

## Security

A hug is code from a team, so CliqHub runs it where it can't reach anything:

* It is served from a **separate content host** (`content.cliqhub.io`), in a frame with `sandbox="allow-scripts"`
  and a strict Content Security Policy: **no network, no storage, no cookies, no navigation, no popups**.
* Everything it does — upload a file, read an attachment, open a link — goes through the Hub page, with the viewer's
  permissions. A link that isn't in the Hug's params is shown to the person before it opens.
* **The Submit button is the Hub's**, outside the frame: a hug can't send an answer by itself.
* CliqHub accepts a bundle only from a daemon of the Hug's realm, and checks its hash and rules.

***

## Examples

In the cliq repo, [`examples/hugs`](https://github.com/getcliqio/cliq/tree/main/examples/hugs) — each with its definition, page, tests and sample params for `cliq hug dev`:

| Example | Shows |
| - | - |
| [`review-batch`](https://github.com/getcliqio/cliq/tree/main/examples/hugs/review-batch) | The tutorial's finished code: a team with its own hug, asked from a custom agent and a model |
| [`review-batch-react`](https://github.com/getcliqio/cliq/tree/main/examples/hugs/review-batch-react) | The same hug with a React page |
| [`triage-list`](https://github.com/getcliqio/cliq/tree/main/examples/hugs/triage-list) | A long list with filters and bulk actions |
| [`compare-versions`](https://github.com/getcliqio/cliq/tree/main/examples/hugs/compare-versions) | Two attachments side by side; choose one with a reason |
| [`image-markup`](https://github.com/getcliqio/cliq/tree/main/examples/hugs/image-markup) | Boxes drawn on an image; a custom view that redraws them |
| [`checklist-signoff`](https://github.com/getcliqio/cliq/tree/main/examples/hugs/checklist-signoff) | An upload slot per item; several reviewers with a `groups` policy |
| [`low-level`](https://github.com/getcliqio/cliq/tree/main/examples/hugs/low-level) | `review-batch` on the raw runtime API |
| [`form`, `approval`](https://github.com/getcliqio/cliq-agents/tree/main/hugs) | The built-in hugs, written the same way ([reference](https://docs.getcliq.io/hugs/reference/form-and-approval.md)) |

***

## Next

> [card] [Tutorial — your first hug](https://docs.getcliq.io/hugs/tutorial.md)
>
> Build `review-batch` end to end.

> [card] [Defining a hug](https://docs.getcliq.io/hugs/defining-a-hug.md)
>
> `define_hug`, `mount_hug` and the UI kit.

> [card] [Using hugs](https://docs.getcliq.io/hugs/using-hugs.md)
>
> From `team.yml`, agent code and LLM phases.

> [card] [Installing](https://docs.getcliq.io/hugs/installing.md)
>
> Team hugs, `CLIQ_HUGS_PATH`, how bundles reach CliqHub.

> [card] [UI kit](https://docs.getcliq.io/hugs/ui-kit.md)
>
> Fields, choices, files and attachments that match the Hub.

> [card] [Security](https://docs.getcliq.io/hugs/security.md)
>
> The sandbox and the trust model in full.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.