ApprovalUI
A tiny open-source loop for reviewing UI fixes inside terminal-based AI agents.
Terminal agents are great for code. They are bad at UI feedback, because UI feedback needs eyes, not paragraphs.
ApprovalUI renders a clickable HTML approval page from a simple JSON spec. You open it in a browser, tick approve or reject per item, generate a review, and paste it back into the agent.
Binary signal. Screenshot attached. No drift.
Why
When you iterate on frontend with a terminal agent, the feedback loop is verbal:
“The divider looks weird — can you make it full height?”
The agent reads text, not pixels. You end up describing the same fix five times.
ApprovalUI short-circuits that loop. The agent writes a structured spec of the fixes, you review them visually, and the page gives you a structured text block to paste back.
Works with Claude Code, Codex, Kimi, or any terminal agent that can write JSON and open a browser.
How it works
- The agent writes a JSON spec describing each UI fix: title, issue number, screenshot, root cause.
approvaluiturns the spec into a self-contained HTML page.- You open the page, review each item, tick Approve or Reject, add comments.
- Click Generate review to get a structured text block you paste back into the agent.
Install
pip install approvalui
Or clone and install in editable mode:
git clone https://github.com/floomhq/approvalui.git
cd approvalui
pip install -e ".[dev]"
Quick start
approvalui example/fixes.json example/approval.html
open example/approval.html
Tick approve or reject, add a comment, and click Generate review.
JSON spec format
{
"title": "Workeros — Fix Approval",
"instructions": "Tick the ones you approve, click Generate review, paste it back to me.",
"items": [
{
"id": 1218,
"title": "Brain split-view divider now runs FULL HEIGHT to the bottom",
"status": "pending",
"root_cause": "wrapper used min-h-full so Collection height:100% could not resolve",
"screenshot": "screenshot.svg"
}
]
}
Only id and title are required. root_cause, screenshot, and instructions are optional.
Generated review format
[APPROVE] #1218 — Brain split-view divider now runs FULL HEIGHT to the bottom
[REJECT] #1219 — Sidebar scrolls horizontally on mobile — comment: still broken on iPhone SE
Documentation
- Docs site
- Architecture
- Advanced usage
- Troubleshooting
- Claude Code example
- Codex example
- Kimi example
Files
src/approvalui/— the Python package.example/— sample spec, screenshot placeholder, and generated page.SKILL.md— Floom skill instructions for agent integration.
Contributing
See CONTRIBUTING.md.
License
MIT. See LICENSE.
Metadata
Release files for approvalui 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| approvalui-0.1.1.tar.gz | 181.9 kB | Without provenance | Details for approvalui-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| approvalui-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for approvalui-0.1.1-py3-none-any.whl |
Total release size: 190.3 kB
Release files / approvalui-0.1.1.tar.gz
| Download URL | approvalui-0.1.1.tar.gz |
|---|---|
| Size | 181.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71a1e5a1bf144eae592ec6477e6a9ec87664ad5dc4cfd8e677f461883dbf6b89
|
|
BLAKE2b-256 checksum How to use checksums |
38fcab9a99b32162142a846bb573ba55258a7e195cc68db615659d408bc8191f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / approvalui-0.1.1-py3-none-any.whl
| Download URL | approvalui-0.1.1-py3-none-any.whl |
|---|---|
| Size | 8.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0d91c462c931305f199464c7866adb49ade88141560d61acd7e72f1049c2bd2a
|
|
BLAKE2b-256 checksum How to use checksums |
431efcb66872005138b81647441294f77c2c6e11a0ddc5e4a22f5410ef32601e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for approvalui 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.