Hugs overview

Hugs

A Hug is a request a run makes of people (Asking people). 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.

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/:

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)
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)
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 — each with its definition, page, tests and sample params for cliq hug dev:

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

Tutorial — your first hug

Build review-batch end to end.

Defining a hug

define_hug, mount_hug and the UI kit.

Using hugs

From team.yml, agent code and LLM phases.

Installing

Team hugs, CLIQ_HUGS_PATH, how bundles reach CliqHub.

UI kit

Fields, choices, files and attachments that match the Hub.

Security

The sandbox and the trust model in full.

Start

Hugs

Agents

CLI

Integrations

Hugs overview

What a hug is

Who does what

The page’s states

Security

Examples

Next

Tutorial — your first hug

Defining a hug

Using hugs

Installing

UI kit

Security

​What a hug is

​Who does what

​The page’s states

​Security

​Examples

​Next

Tutorial — your first hug

Defining a hug

Using hugs

Installing

UI kit

Security

What a hug is

Who does what

The page’s states

Security

Examples

Next