How Agent Pit Stop works

The problem it was built to solve, the loop it's designed around, and the system it's made of.

What is Agent Pit Stop?

Agent Pit Stop is an open-source design system for agent interfaces: five UX principles with live demos, and production React components for the moments where agents and humans sync. Approval, inspection, handoff, recovery. I write it from a designer's lens, having shipped agentic products since 2021, and everything is MIT and built to be copied.

npx shadcn@latest add https://agent-pitstop.vercel.app/r/approval-gate.json

import { ApprovalGate } from "@/components/approval-gate";

<ApprovalGate
  title="Send the Q3 summary email?"
  scope={[{ label: "Send to 3 recipients", risky: true }]}
  onApprove={send}
  onDeny={cancel}
/>

A few things set it apart. It covers the interface layer, not the architecture. Most agentic design writing explains orchestration and memory to ML engineers; this system covers what the human actually sees, approves, interrupts, and trusts. Every claim has living evidence. Each principle chapter embeds the working components that prove it, and each component page cites the principles it applies. You own the code. Components are single files with three dependencies (React, Tailwind, Motion); install them through the registry or copy the source, and there is no library to wrap, version, or fork.

The problem

Every team shipping an agentic product designs the same moments from scratch: how to show a tool call, when to ask permission, what a stop button should do to in-progress work, how confident an extraction should look. I rebuilt those moments at a conversational AI startup, at a medical documentation company, and in an agentic capture app I co-founded. Three products, three hand-rolled versions of the same interface, and each time the pattern knowledge existed only as scars. Agent Pit Stop is those scars written down, made installable, and argued for, so the next team starts from a system instead of a blank canvas.

The loop

The whole system hangs on one model. Agents run laps on their own; the pit is where humans intervene. Design the pit well and users delegate more laps, the same way drivers go faster in cars with better brakes.

Every component serves a station on this circuit. The Approval Gate is the contract at the start line. Tool Call Cards and the Agent Task List are the telemetry that make the lap legible. The Confidence Meter and failure states are pit triggers. The Interrupt Bar is the brake and the steering wheel. The principles are the racecraft: when to interrupt, how to show uncertainty, what a failure owes the driver.

Principles as promises

Built to be copied. Single-file components, MIT, no wrapper API. The graduated path is: install from the registry, restyle with your tokens, or take the source and own it entirely.

Evidence over opinion. No pattern ships as prose alone. If a principle can't be demonstrated with a working component, it isn't done being designed.

One system for humans and agents. The registry endpoints are machine-readable JSON with full source, and the contract an agent consumes is generated from the component TypeScript at build time: descriptions, props, and principle tags are parsed from source, never hand-typed, so the feed cannot drift. A dense, prose-free version sized for a context window lives at /r/contract.json, and it carries something prop schemas can't: the behavioral guarantees each component makes, derived from the principles.

Designed for the pit, not the lap. The system spends its effort on the sync moments. What the agent does autonomously is your product; what happens when a human leans in is what we make excellent.

Make it yours

Every component speaks in semantic tokens, never raw values. That means the whole system rethemes from one place: define the tokens in your Tailwind theme with your own values, and every card, gate, and meter follows. No wrapping, no forking, no component edits.

@theme {
  /* surfaces */
  --color-track: #0a0a0b;    /* page */
  --color-asphalt: #131316;  /* component surface */
  --color-carbon: #0e0e10;   /* card surface */
  --color-barrier: #1f1f24;  /* raised surface */
  --color-line: #2c2c33;     /* borders */
  /* text */
  --color-chalk: #ececf1;    /* primary */
  --color-smoke: #9a9aa3;    /* secondary */
  --color-ash: #7f7f8a;      /* tertiary (keep >= 4.5:1) */
  /* signals */
  --color-pit: #fb923c;      /* accent: swap for your brand */
  --color-signal: #34d399;   /* success */
  --color-caution: #fde047;  /* attention */
  --color-flag: #f87171;     /* danger */
}

Past tokens, the path escalates one step at a time: pass className for layout and overrides, or take the single source file and own it entirely. Keep the contrast honest when you retheme; the tokens above all clear WCAG AA on their surfaces.

The name

A pit stop is the moment a fast autonomous thing submits to human hands: twelve seconds of inspection, correction, and consent, then back out at speed. That is exactly the shape of good agent UX, and it names both halves honestly: the agent's job is to run laps, and the interface's job is to make the stops fast, legible, and worth trusting. Also, we wanted to go fast.

Open source

git clone https://github.com/acaspx/agent-pitstop

Agent Pit Stop is MIT licensed and early: five principles, five components, one new piece shipping weekly. The roadmap is public, issues are open, and the best way to shape it is to tell me which sync moment your product is struggling with. Welcome to the pit.