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.
$ npx shadcn@latest init:root {
--accent-violet: #a78bfa;
--accent-amber: #fbbf24;
--accent-emerald: #4ade80;
--accent-rose: #fb7185;
--accent-blue: #007AFF;
}UI primitives
20 componentsInterrupt 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.jsonSubagent 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.jsonMiniTrace
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.jsonAI 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.jsonAI 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.jsonAI 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.jsonAI 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.jsonContext 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.jsonQA 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.jsonWriting 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.jsonResearch 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.jsonBatch 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.jsonSearch 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.jsonApprove / 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.jsonShared 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.jsonDiff 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.jsonCitation 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.jsonEditable 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.jsonTool 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.jsonEvidence 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.jsonLib & shared
6 utilitiescn utility
Tailwind classname merge helper used by every HITL Kit primitive.
$ npx shadcn@latest add https://www.hitlkit.dev/r/hitl-utils.jsonHITL 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.jsonShared 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.jsonSubagent 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.jsonAI 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.jsonDemo 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.jsonConventions.
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.