The registry.

Install any primitive with one command. HITL Kit ships as a shadcn-compatible registry. Every primitive below installs directly into your existing shadcn/ui project. No fork, no wrapper SDK, no lock-in.

Before you install.

You need a Tailwind project with the shadcn CLI initialized. HITL Kit also uses custom CSS variables for accent colors (violet, amber, blue, emerald, rose). Add these to your globals.css.

1 · Initialize shadcn (if you haven't)
$ npx shadcn@latest init
2 · Add HITL Kit tokens to globals.css
:root {
  --accent-violet:  #a78bfa;
  --accent-amber:   #fbbf24;
  --accent-emerald: #4ade80;
  --accent-rose:    #fb7185;
  --accent-blue:    #007AFF;
}

UI primitives

20 components
UIhitl-card

Interrupt Card

In-thread approval boundary for agent actions. Three semantic variants (search, review, write). Idle, expanded, confirmed and dismissed, and every resolution can be undone.

$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-card.json
Depends on:hitl-utilshitl-typeshitl-shared
UIsubagent-status-card

Subagent Status Card

Single-row agent status with icon, label, detail, and state in words. Use to wrap any in-progress agentic task.

$ npx shadcn@latest add https://www.hitlkit.dev/r/subagent-status-card.json
Depends on:hitl-utilshitl-subagent-meta
UImini-trace

MiniTrace

Collapsible step-by-step renderer for agent reasoning. Thought, action, result. Makes supporting facts visible per §3.3 of the paper.

$ npx shadcn@latest add https://www.hitlkit.dev/r/mini-trace.json
Depends on:hitl-utilshitl-shared
UIai-generation-scale

AI Generation Scale

Five-segment ordinal scale indicating AI involvement in a piece of work. Embodies the scaffolding and expertise-matching principle from Dhillon et al. (2024).

$ npx shadcn@latest add https://www.hitlkit.dev/r/ai-generation-scale.json
Depends on:hitl-utilshitl-ai-levelshitl-shared
UIai-generation-slider

AI Generation Slider

The compact drag form of the AI generation scale. One header row and one track, no wrapping at 320px. Pointer drag snaps to five stops; arrow keys step and Home/End jump. Full slider ARIA.

$ npx shadcn@latest add https://www.hitlkit.dev/r/ai-generation-slider.json
Depends on:hitl-utilshitl-ai-levels
UIai-generation-meter

AI Generation Meter

At-a-glance, read-only provenance for a list row or a header. Five thin segments filled to the current level plus the level name, as a single role=img element with no focusable children.

$ npx shadcn@latest add https://www.hitlkit.dev/r/ai-generation-meter.json
Depends on:hitl-utilshitl-ai-levels
UIai-generation-badge

AI Generation Badge

The densest form of the AI generation scale: one pill with a five-dot micro-indicator and the level name. Static by default; given onAction it grows stepper buttons with 24px hit areas.

$ npx shadcn@latest add https://www.hitlkit.dev/r/ai-generation-badge.json
Depends on:hitl-utilshitl-ai-levelshitl-shared
UIcontext-chips

Context Chips

Pill chips representing context attached to an agent run. Notes, files, URLs. Removable with overflow truncation.

$ npx shadcn@latest add https://www.hitlkit.dev/r/context-chips.json
Depends on:hitl-utilshitl-shared
UIqa-flow

QA Flow

Multi-question approval card. Single-choice, multi-select, and freeform text. Submits to a resolved line that keeps the answers visible and can be reopened.

$ npx shadcn@latest add https://www.hitlkit.dev/r/qa-flow.json
Depends on:hitl-utilshitl-typeshitl-shared
UIwriting-agent

Writing Agent

Compound widget for a draft-in-progress document. Title, target section, word range, evidence notes, and six status states.

$ npx shadcn@latest add https://www.hitlkit.dev/r/writing-agent.json
Depends on:hitl-utilshitl-subagent-metahitl-shared
UIresearch-agent

Research Agent

Three-mode config surface for a long-running research task. Create, follow-up, read URL.

$ npx shadcn@latest add https://www.hitlkit.dev/r/research-agent.json
Depends on:hitl-utilshitl-shared
UIbatch-queue

Batch Approval Queue

Sequential approve and reject flow across mixed agent items. Auto-advances, can step back one item, and resolves to a summary state.

$ npx shadcn@latest add https://www.hitlkit.dev/r/batch-queue.json
Depends on:hitl-utilshitl-typeshitl-shared
UIsearch-result-card

Search Result Card

Ranked search result card with rank badge, metadata, snippet, and relevance bar.

$ npx shadcn@latest add https://www.hitlkit.dev/r/search-result-card.json
Depends on:hitl-utils
UIapprove-reject-row

Approve / Reject Row

The canonical decision row. Approve, reject, or can't tell; pending, approved, rejected, abstained; undo back to pending.

$ npx shadcn@latest add https://www.hitlkit.dev/r/approve-reject-row.json
Depends on:hitl-utilshitl-shared
UIshared-primitives

Shared Primitives

The atomic palette. Accent swatches, the four approval badges, and the decision row that sets them.

$ npx shadcn@latest add https://www.hitlkit.dev/r/shared-primitives.json
Depends on:hitl-utilsapprove-reject-row
UIdiff-result

Diff Result

Before/after diff card for proposed text or code edits. Per-hunk red/green strips; apply, keep original, or can't tell; undo. The primitive for any in-place edit the human should approve before it lands.

$ npx shadcn@latest add https://www.hitlkit.dev/r/diff-result.json
Depends on:hitl-utilshitl-typeshitl-shared
UIcitation-result

Citation Result

Single source-backed citation card. Claim on top, source attribution below, optional supporting quote and confidence. Verify, reject, or can't tell; undo.

$ npx shadcn@latest add https://www.hitlkit.dev/r/citation-result.json
Depends on:hitl-utilshitl-typeshitl-shared
UIeditable-plan

Editable Plan

Multi-step plan the human can reorder, rename, add to, or delete from before the agent executes. Locked steps cannot be removed. Submit or cancel; undo.

$ npx shadcn@latest add https://www.hitlkit.dev/r/editable-plan.json
Depends on:hitl-utilshitl-typeshitl-shared
UItool-call-preview

Tool Call Preview

Preview a tool call (name, args, optional rationale and signals) so the human can approve, reject, or say they can't tell before execution. External scopes are flagged. Pairs with the gates layer.

$ npx shadcn@latest add https://www.hitlkit.dev/r/tool-call-preview.json
Depends on:hitl-utilshitl-typeshitl-shared
UIevidence-pointer

Evidence Pointer

Where a claim is grounded, not merely that it is. One row per pointer with source, locator in human units, and excerpt; sources consulted but not drawn from are listed so silence never reads as safety. Grounded, not supported, or can't tell; undo.

$ npx shadcn@latest add https://www.hitlkit.dev/r/evidence-pointer.json
Depends on:hitl-utilshitl-typeshitl-shared

Lib & shared

6 utilities
Libhitl-utils

cn utility

Tailwind classname merge helper used by every HITL Kit primitive.

$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-utils.json
Libhitl-types

HITL UI types

The props every decision surface shares (busy, error, help, allowAbstain, allowUndo, autoFocus) and the interrupt card's local state. Event and action types come from @hitl-kit/core.

$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-types.json
Libhitl-shared

Shared decision pieces

The card frame, decision bar, resolved line, inline error, help line and chip that every decision surface is built from. One vocabulary, one set of button styles.

$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-shared.json
Depends on:hitl-utils
Libhitl-subagent-meta

Subagent status metadata

Shared icon, color and plain label for the six agent execution states (idle, running, completed, error, skipped, cancelled).

$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-subagent-meta.json
Libhitl-ai-levels

AI generation levels

The five-point AI-generation ordinal and its accent progression, shared by every scale variant so a level cannot mean one thing in the slider and another in the badge.

$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-ai-levels.json
Libhitl-fixtures

Demo events

Valid core events for the decision surfaces, for demos and tests. Spread one onto its primitive or feed it to HitlEventRenderer.

$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-fixtures.json

Conventions.

Target path

All UI primitives land under components/hitl/, lib entries under lib/. The shadcn CLI respects your components.json aliases.

Dependencies

The CLI will auto-install npm packages (like lucide-react) and transitive registry deps (like hitl-utils) for you.

Copy-paste ownership

Once installed, the files are yours. Edit them freely. This is the shadcn model. No npm update, no breaking-change anxiety, no framework lock-in.

LLM pluggability

Each primitive ships with a Zod event schema and a dispatch renderer, so LangGraph and Vercel AI SDK agents can stream structured HITL events that render automatically.