Pinrail: A Dedicated Desktop Inbox for Agentic Review

Pinrail Logo

Pinrail is a specialized desktop application designed to implement a human-in-the-loop system for AI coding agents. Instead of granting agents total autonomy, Pinrail acts as a staging area where agents must request permission before executing critical actions.

You review the agent's proposal within a tailored interface, and once you provide a decision, the agent proceeds based on your feedback.

Compatibility & Status

Pinrail is compatible with any agent capable of executing shell commands, including:

Claude Code
Codex
Cursor
OpenCode

[!IMPORTANT] Pinrail is currently in early development. Users should anticipate ~~polished stability~~ some rough edges and frequent changes between versions.

The Philosophy: Why a Dedicated Inbox?

While agents are highly efficient at executing tasks, certain milestones require human judgment. Examples include:

Sending an email to a client.
Deploying changes to a production environment.
Posting a public comment under your identity.

Approving these actions via a standard chat interface often involves ~~sifting through a wall of text~~ reading massive logs and typing repetitive confirmations. Pinrail transforms these moments into structured reviews:

Selective Interruption: The agent only asks for help at steps explicitly defined in its instructions.
Contextual Views: A code review displays a diff with specific findings; an image review allows you to draw bounding boxes on areas needing adjustment.
Actionable Feedback: The agent receives your acceptances, rejections, and notes as either JSON (for scripts) or Markdown (for LLM processing).
Privacy First: The API operates exclusively on the loopback interface, ensuring all decisions and reviews remain stored locally.

Technical Workflow

The interaction follows a simple request-response cycle:

The Submission Process

When an agent hits a required checkpoint, it triggers the pinrail CLI:

pinrail submit code-review --title "Retry failed webhook deliveries" \
--data findings.json --wait

The review then appears in your project-grouped inbox. For a code review, you might interact with the findings like this:

Review Result Example: r_01K5R2 $\cdot$ decided $\cdot$ Retry failed webhook deliveries Decided by maya on 2026-09-23 10:14

#1 Accepted $\rightarrow$ $\to$ src/deliver.ts:42 — The worker sleeps for up to 31 seconds per delivery (major)
- Note: Agreed. Re-enqueue using the formula: $\text{runAt} = \text{now} + \text{backoff}(\text{attempt})$
#4 Rejected $\rightarrow$ $\to$ src/log.ts:18 — The give-up log should say why (nit)
- Note: This is fine; the log already includes the delivery ID.
Undecided: #2, #3, #5

The command's exit code communicates the final state: decided, discarded (stop agent), withdrawn, or expired. If changes are requested, the agent submits a new round, and Pinrail displays previous verdicts side-by-side for comparison.

Getting Started

Install: Download the app from the official release or download page.
Setup: The installer configures the pinrail command, integrates the Pinrail "skill" into detected local agents, and loads default plugins.
Test: Give your agent a prompt such as:
- "Use Pinrail to ask me which TODOs in this repo I should prioritize."
- "Analyze this project and suggest where Pinrail checkpoints would be most useful."

The Plugin System

Every review type is powered by a plugin, which defines the input payload, the output decision, and the visual interface.

Core Plugins

Plugin	Purpose	Interaction Style
`code-review`	Code Analysis	Diff view with accept/reject/edit options for comments.
`list`	Item Selection	Grouped items with notes and binary choices.
`feedback`	General Q&A	Multiple choice, Yes/No, or free-text responses.
`markdown`	Document Review	Section-by-section commentary on specs or plans.
`image`	Visual Review	Image selection with pins and boxes for modifications.

Extended Capabilities

Additional samples are available at forgeplane/pinrail-plugins, covering diverse needs such as:

3D models & Animations
Audio & Video
Color palettes & Logos
Email & Calendar events
HTML pages & Design canvases

Developing Plugins

Plugins are lightweight; they consist of a manifest, two JSON schemas, and an HTML view—no build step required.

Creation: Use pinrail plugins new <name>.
Testing: The pinrail-sdk allows you to run views in a browser independently of the app and perform tests via Playwright.