Introduction

nitpin is the UI-refinement loop for macOS — sweat the details, ship the delight.

It’s the tool for nailing the small things that separate a generic, just-functional interface from a delightful one: the misalignments, the rough edges, the half-second of jank, the final touches. In an era where the first cut of a UI is increasingly machine-generated, nitpin is the layer that makes it feel crafted. You pin the nits; your coding agent refines them.

How it works

You drive your own app — a browser, the iOS Simulator, an Android emulator, anything. nitpin only captures: a global hotkey freezes a window’s pixels, and you drop pins and regions with notes on the still. Each capture is saved as an issue in a per-project store. Your coding agent then reads those issues over MCP — looking at the actual screenshot, locating the responsible code, fixing it, and recording what changed.

┌─────────────┐   capture (⇧⌘6 / ⇧⌘7)   ┌──────────────┐   /nitpin    ┌──────────────┐
│   Your app  │ ──────────────────────▶ │  nitpin app  │ ───────────▶ │ Coding agent │
│ (browser…)  │   pin / region + note   │  (menu bar)  │   over MCP   │  fixes code  │
└─────────────┘                         └──────────────┘              └──────────────┘

What you capture

• Issue — one capture (a frozen screenshot). It has a number (#3), an auto-generated title, and an optional top-level body note.
• Sub-issue — one problem on that capture: a pin on a precise spot, a region around an area, or a note about the whole frame. Sub-issues are numbered within the issue — the badges you see on the annotated image.
• Each sub-issue has a status — unresolved → fixed / won’t fix — and the issue’s state rolls up from its sub-issues.

You never manage any of this by hand. You drop pins and type notes; nitpin writes the store for you.

The promises

• Capture-only. nitpin reads pixels and window metadata. It never clicks, types into, or navigates your apps — that’s the whole product promise. Even in Live mode, you drive the page; nitpin only freezes it.
• Local-first. Your issues are plain files — YAML and PNGs — in your repo or on your machine. Screenshots, notes, and code never leave your device.
• Your words are immutable. Once captured, an issue’s body and notes are never edited. Agents speak through comments and resolve notes, kept separate from what you wrote.

Requirements

• macOS 26 (Tahoe) or later.
• A coding agent with MCP support — Claude Code, Codex, OpenCode, or Pi.
• Screen Recording permission, granted on first run — nitpin needs it to read window pixels (and only reads them when you take a shot; it never records continuously).

Where to go next

• Installation — get the app and the CLI.
• Your First Loop — capture a nit and watch an agent fix it, in about two minutes.
• CLI Reference and MCP Tools — the full command and tool surface.

Installation

nitpin is two pieces that work as one:

• the menu-bar app — you capture and review with it, and
• the nitpin CLI — it wires your repo to your coding agent and runs the MCP server the agent talks to.

Install the app

Download nitpin for macOS from nitpin.com, open the DMG, and drag nitpin to Applications. The app lives in the menu bar (no Dock icon) — look for the pin-on-pane icon.

On first launch, nitpin asks for Screen Recording permission (System Settings › Privacy & Security › Screen Recording). It needs this to read a window’s pixels when you capture — it freezes pixels only when you take a shot and never records continuously. macOS requires the app to relaunch once after a fresh grant; nitpin offers a “Quit & Reopen” when that’s the case.

Install the CLI

The easiest path is from the app: Settings › General › Command-line tool › Set up… installs the nitpin command and wires the MCP server and skill into your coding agents in one step.

You can also install it from a terminal:

curl -fsSL https://install.nitpin.io | bash

Either way you end up with the nitpin command on your PATH.

Wire up your coding agents

To make nitpin available to your agents in every repo (a one-time, user-global install), run:

nitpin install          # interactive wizard — pick the agents to set up
nitpin install claude   # or set up just one

nitpin supports four coding agents:

The wizard detects which ones you have and installs the nitpin MCP server plus the nitpin skill (or an agent-instructions section, depending on the harness) for each. Re-running nitpin install skips agents that are already up to date — pass --force to reinstall — and nitpin uninstall removes everything again. Restart your agent after installing so it picks up the new MCP server.

nitpin never installs a third-party coding agent for you — it only wires itself into the ones you already have.

Stay up to date

The app updates itself: when a new version is ready, a teal Update banner appears at the top of the menu-bar popover (and an ↑ Update pill in the Cockpit’s status bar). One click on Install Update in Settings › General downloads, verifies, and relaunches. A standalone CLI updates with nitpin update; a CLI that shipped inside the app is updated by the app itself.

Next

With both pieces installed, set up your first project — or jump straight to your first loop.

Your First Loop

The whole point of nitpin is a tight loop: see a nit → pin it → an agent fixes it. Here’s the full round trip, end to end.

1. Set up the project

In the repo you’re refining:

nitpin init      # creates ./.nitpin/, wires up .mcp.json, installs the skill
nitpin open      # makes it the app's current project and raises the Cockpit

nitpin init creates the project’s issue store inside your repo, so issues travel with the code. It also writes the MCP configuration your agent reads and drops the nitpin skill in place. (No repo handy? Create a project straight from the app instead — see Projects.)

2. Capture a nit

With a window of your app visible, press ⇧⌘6. A full-screen picker highlights windows as you hover — click one to freeze it.

On the frozen still:

• Click to drop a pin on a precise spot, or drag to mark a region.
• Type a note for each mark — that’s the sub-issue’s text. Write it the way you’d describe the bug to a teammate.
• Optionally add a top-level note in the “What’s the nit?” field for the capture as a whole.
• Press ⌘Return to save.

The capture flies into the menu-bar icon and lands in your project as an issue, titled automatically on-device.

Your notes are the spec; the title is a guess. The issue title is synthesized from your text and is just a label — your notes and body are what the agent reads and follows.

3. Let an agent fix it

Open your coding agent (Claude Code, Codex, …) in the same repo and type:

/nitpin

— or just say “check nitpin” or “fix the QA feedback”. The agent will:

1. Triage if needed — group related issues into session-sized clusters.
2. Claim one cluster (or a single issue) so other agents skip it.
3. Look at the screenshot — focused crops of exactly where each pin points.
4. Find the code, make the fix, and resolve each sub-issue with a short note about what changed.
5. Stop when that one logical chunk is done and summarize.

You can also skip the agent-side prompt entirely and click Fix on an issue in the Cockpit — see Dispatching Fixes.

4. Watch it happen

While the agent works, the app’s Cockpit window updates live: issues regroup into clusters, a breathing teal dot marks whatever is claimed, a one-line progress note tells you what the agent is doing right now, and sub-issues flip to resolved as the fixes land. From the Cockpit you can read, comment, reopen, or stop an agent at any point.

That’s the loop. Capture freely — pins are cheap, and the backlog is the agent’s problem now.

Projects

A project collects the issues you capture for one app or repo. nitpin keeps a list of your projects; exactly one is active at a time — that’s where new captures land.

Creating a project

From the app (menu bar › New Project…, or the Cockpit’s project menu), name the project after the app or repo you’re testing and pick where it lives:

• In nitpin — start capturing now, link code later. The project is stored under nitpin’s own folder on your machine. Perfect when you just want to start pinning.
• In this repo — store issues with the code. Creates a .nitpin/ folder inside the repo you choose and wires up your coding agent there (this is the same thing nitpin init does from a terminal). Issues are committed alongside the code, so they travel with it.
• Clone from Git — paste a repository URL; nitpin clones it and creates (or adopts) its project in one step. See Sync Issues with Git.

From a terminal, the equivalents are:

nitpin init              # a .nitpin/ store in the current repo
nitpin init --path DIR   # store the project elsewhere, leaving a pointer in the repo
nitpin clone URL         # clone a repo and open its project

Switching and opening

• The menu-bar popover header shows the active project; click the chevron to switch. The Cockpit’s rail title opens the same switcher, plus Open… for browsing to a project folder on disk.
• From a terminal, nitpin open activates the project for the current directory and raises the Cockpit; nitpin projects lists everything nitpin knows about.

Linking a repo to an existing project

If your project lives “in nitpin” but you want captures to be fixable from a particular repo, link them:

cd path/to/repo
nitpin link              # pick from your known projects
nitpin link my-app       # or name one directly

Linking writes a small nitpin.yaml pointer in the repo so agents and CLI commands run there resolve to the right project. nitpin unlink removes the pointer again.

The link is also how a project gains a Source — the code folder shown in Project Settings, used by fixes, Tune, and git sync.

Project settings

Each project carries its own workflow settings — how agents work (parallel worktrees or one at a time), where fixes land (main or a review branch), what happens when an agent hits ambiguity, auto-triage, and more. They’re all in the Cockpit under Project Settings…, and machine-wide defaults for new projects live in Settings › Projects. The full list is in the Settings reference.

Where projects live

New “in nitpin” projects are stored under a default folder you can change in Settings › General › New projects. In-repo projects live in their repo’s .nitpin/ directory. Either way, a project is just a folder of plain files — see Where Your Data Lives.

Capture a Window

nitpin captures any macOS window — your browser, the iOS Simulator, an Android emulator, a native app. Two modes cover two situations, each with its own global hotkey (they extend Apple’s ⇧⌘3/4/5 screenshot family and work system-wide while nitpin is running).

Deliberate capture — ⇧⌘6

Press ⇧⌘6 (or click Capture a window in the menu-bar popover, or Capture Window in the Cockpit). The screen dims and a crosshair appears; hovering highlights capturable windows Safari-style. Click one to freeze it into the annotation editor.

Use this when you have a moment to aim — it’s the everyday mode.

Quick capture — ⇧⌘7

Press ⇧⌘7 and nitpin freezes the window under your cursor immediately — before any overlay appears — into a lightweight, non-activating editor. Because nothing steals focus first, the UI you’re pointing at survives the capture.

Use this for transient UI: open menus, tooltips, popovers, hover states, drag previews — anything that vanishes the moment your app loses focus. (A beep means there was no capturable window under the cursor.)

Good to know

• Both hotkeys are configurable in Settings › General › Capture. If a combo is already taken by another app, nitpin shows a warning and asks you to pick another.
• Capture is paused while the Settings window is open.
• Capturing never touches the target app — nitpin reads pixels and window metadata (the app’s name and window title, saved as the issue’s provenance) and nothing else.
• For web apps, there’s a third way that skips windows entirely: Live mode.

Annotate the Still

Once a window (or a Live page) is frozen, you’re in the annotation editor. Everything here is about saying what’s wrong, where — fast.

Marks: pins and regions

• Click the still to drop a pin on a precise spot — a misaligned icon, a stray pixel.
• Drag to draw a region around an area — a whole card, a section with the wrong spacing.

Each mark becomes a numbered sub-issue in the panel docked beside the still, with its own note field. Write each note the way you’d describe the bug to a teammate — your notes are exactly what the agent reads.

The body note

The “What’s the nit?” field at the top holds a note about the capture as a whole — “this whole screen feels cramped”, “dark mode colors are off everywhere”. A capture can be just a body note, just marks, or both.

One note, several places

Sometimes one problem lives in several places — the same misaligned label on three cards. Instead of writing the note three times, select the sub-issue and use + Add place to attach more pins or regions to it. A single-anchor sub-issue badges plainly (2); a multi-anchor one badges its places with letters (2a, 2b, 2c).

Referencing marks in text

Type #2 in any note to refer to sub-issue 2, or #2a to point at one specific place of a multi-anchor sub-issue. Hovering a reference flashes the mark it points to — handy for notes like “make #3 match #1”.

Tags

Add #word tags anywhere in a note or the body — #ios, #dark-mode, #checkout. Tags autocomplete against the project’s existing tags, cross-cut the backlog, and can be used to filter what an agent works on (“fix the #ios issues”). See The nitpin Skill.

Reference images

Paste an image (⌘V) into the body or any note to attach it inline — a mockup, the desired end state, an example to match. It shows as a pill in the text and rides along with the issue; agents view it as part of the intent, right at the point in the note where you pasted it.

Redaction

Sensitive content on screen? Mark a region as redacted and it’s pixelated before the capture is saved — the sensitive pixels never reach disk.

Keyboard

What gets saved

Saving writes one issue to the active project: your sub-issues and body, a clean screenshot, an annotated render with the badges drawn on, and any pasted images. The issue is titled automatically on-device from your text (3–5 words, text-only — the screenshot is never sent anywhere). The title is just a label; your notes are authoritative, and once saved they’re immutable — agents can comment, but never edit your words.

Live Mode

Live is nitpin’s built-in capture surface for web apps: your running app, hosted inside the Cockpit, with the capture loop one keystroke away — no separate browser, no window-picking.

Enter and leave Live with ⌥⌘L, or the Capture Live button in the Cockpit rail. The Cockpit chrome tints orange while you’re in it.

You drive; nitpin watches

Load your app (the address field suggests localhost:3000) and use it exactly as you would in a browser — click around, fill forms, get it into the state you want to critique. nitpin never navigates, clicks, or types for you:

Your app stays in your hands. nitpin reads the page; it never drives it.

The browser strip has Reload (⌘R), the address field (⌘L focuses it), and a Capture button (⌘⇧C).

Freeze and annotate

Hit Capture to freeze the page. The frozen state hosts the exact same annotation editor as a window capture — click for a pin, drag for a region, type notes, then Save (⌘S). Recapture re-freezes after you’ve changed the page.

What Live adds over a window capture

• Element hints. As you drop each pin or region, nitpin silently reads the DOM element under it and records a best-effort CSS selector and DOM path. Agents use the selector to jump straight to the right component, and you can grab it yourself via Copy selector in the Inspector.
• Provenance. The issue records the page URL and viewport size, so “where was this?” is never a question.
• Viewport presets. Size the page like a device before you capture: phone presets (iPhone SE, iPhone 16, iPhone 16 Pro Max, …), tablets, desktop widths, a Fit mode, or custom sizes.
• Page theme. Flip the page between System / Light / Dark to chase down dark-mode nits without touching your OS setting.

Session housekeeping

Live keeps an isolated web session per project — your logins and storage there don’t mix with your real browser. Reset web storage… (in the overflow menu) signs out and clears cookies, local storage, and caches for the project’s Live session.

Around the Cockpit

The Cockpit is nitpin’s full working window for the current project — where you review captures, talk to agents, triage, dispatch fixes, and watch everything happen live. Open it from the menu-bar popover (Open Cockpit) or with nitpin open from a terminal.

The zones

The window is one continuous pane, organized left to right:

• Command rail (top) — the project switcher, the current operating mode, a live presence cluster showing who’s working, and the capture buttons (Capture Window ⇧⌘6 · Capture Live ⌥⌘L).
• Backlog (left) — every issue in the project, grouped and sorted. See Working the Backlog.
• Stage (center) — the selected issue’s screenshot, hero-sized, with its sub-issues beside it; or the Live surface when you’re in Live mode.
• Inspector (right) — details, the discussion thread, and the action rail for the current selection.
• Status bar (bottom) — activity chips, the sync pill, live token readouts during fixes, and update notices.

Operating modes

The Cockpit expresses what’s happening right now by faintly tinting its chrome and naming the mode in the rail:

You never set a mode; the Cockpit reflects reality. The same signals reach the menu bar too — the pin icon glows while an agent is at work, so you can close the Cockpit and still know.

Everything is live

The Cockpit is built to be watched. Issues regroup as triage lands, claim indicators breathe on whatever an agent holds, a one-line progress note under each claimed issue tells you what the agent is doing right now, resolutions flip in place, and costs tick up in the status bar. If something looks wrong, everything is one click away — reply in the thread, stop an agent, or revert a fix.

Working the Backlog

The Backlog is the left column of the Cockpit: every issue in the project, grouped into clusters after triage, with the controls to sort, search, and dispatch.

Issue states

An issue’s state rolls up from its sub-issues:

The masthead reads BACKLOG · N OPEN (green at all-clear) with a sort toggle (by priority ⇄ by recent) and a search field (⌘F). Below the open issues, Resolved collects finished work, and an Archived disclosure folds away older resolved issues (how many stay visible is a project setting).

The Stage and Inspector

Select an issue and its screenshot takes the Stage — the annotated frame with every badge drawn on. Select a sub-issue to focus its exact spot, read its note, and act on it. The Inspector’s Details show provenance (app, window, URL and viewport for Live captures), and its Actions rail always offers one keyboard-first primary action (⌘⏎) plus the rest:

• Mark Fixed / Won’t Fix / Reopen — resolve or reopen a sub-issue by hand (or the whole issue at once).
• Fix — dispatch an agent at this issue or sub-issue; Fix with ▸ picks a specific agent, model, and effort. See Dispatching Fixes.
• Copy selector — on Live captures, the CSS selector under the mark.
• Revert fix — undo a landed fix with a fresh commit. See Reverting a Fix.
• Below a Careful rule: Stop agent (stops the agent working this issue and releases its claim) and Delete issue (moves it to the Trash — nitpin asks first, and warns if an agent currently holds it).

Priorities and ordering

Drag issues to reorder them — order is priority, and agents work the backlog in the order you set. Within a triaged backlog you can also drag an issue onto another cluster, or use Move to ▸ / Ungroup from its context menu; nitpin remembers those placements as your corrections and preserves them across re-triages.

Who’s working what

A breathing teal dot marks any issue or cluster an agent currently holds, with the agent’s name and a live progress line. The rail’s presence cluster aggregates everything running; click it for the roster — who’s on what, with per-run Stop buttons. Claims expire on their own if an agent dies, so nothing stays stuck — but Stop agent is always there when you want something back now.

Captured content is immutable

One thing the Cockpit deliberately won’t do: edit a capture. The screenshot, your notes, and the body are frozen at capture time. Status, priority, comments, and deletion are yours; the words and pixels stay as captured.

Comments & Discussion

Every issue carries a discussion thread — the one place you and the agents talk. It lives in the Inspector’s Discussion section, scoped to what you’ve selected: select the issue for the whole thread, select a sub-issue to focus its part of the conversation.

How agents use it

Comments are an agent’s only voice. Your captured notes are never edited; everything an agent has to say arrives as comments — questions when a note is ambiguous, a short “what I changed” note on every resolution, and a reason on every won’t-fix. Agent authors show in teal with their name (so parallel agents are easy to tell apart), and comments can be tagged to a specific sub-issue.

Replying

Click Reply…, type, and press Return (⇧Return for a newline). Agents read the thread every time they pick an issue up — a reply to an agent’s question is treated as instruction, so this is exactly how you unblock a parked question or steer a fix without re-capturing anything.

Comments support the same niceties as capture notes: paste an image (⌘V) to attach a mockup or an example inline, and reference marks with #2 / #2a tokens.

When to comment vs. re-capture

• The fix landed but isn’t quite right → reply on the sub-issue with what’s off.
• You have new information (“this only happens on iPad”) → comment.
• It’s a genuinely different problem → capture it as a new issue; threads stay focused, and captures are cheap.

Suggested Issues

Agents notice things. While fixing your captures they often spot improvements just outside what you pinned — the same misalignment on a sibling screen, a hard-coded color, a missing hover state. Rather than silently widening a fix (scope creep) or burying the observation in a comment (where nothing would ever act on it), agents file suggestions.

Where they show up

Suggested issues collect in a SUGGESTED · N section of the Backlog, marked with a lightbulb, above your resolved issues. Each one is a real issue — it carries the source capture’s screenshot, agent-placed pins or regions, and concrete notes about the proposed change — but it’s pending: invisible to agents, triage, and fix runs until you decide.

Deciding

Every suggestion offers three verbs:

• Accept (⌘⏎) — moves it into the open backlog like any captured issue.
• Accept & Fix — accepts and immediately dispatches an agent at it.
• Dismiss — declines it; it folds away as won’t-fix.

An Accept all capsule clears the pen in one go when the agent had a good day.

Suggestions link both ways: a suggested issue names the issue it came from, and the source issue lists what was suggested off it — so the provenance is always one click away.

Nothing in nitpin acts on a suggestion until you accept it. Agents that mint suggestions are explicitly forbidden from claiming or working them — the review is yours.

Clusters, Sizes & Briefs

Capture enough nits and the backlog turns into a pile. Triage turns the pile into a plan: a coding agent reads your open issues and organizes them — without fixing anything, and without ever touching your source code.

Clusters

Triage groups related open issues into clusters — session-sized bundles that share a screen, a component, or a root cause (“Settings dialog spacing”, “Dark-mode contrast issues”). Each cluster gets a short label and a one-line theme summary, and the Backlog regroups around them as cards. Issues that don’t relate to anything stay in an Ungrouped card.

Clusters are the unit of agent work: “fix one cluster” is one focused, reviewable session. They’re also the unit of parallelism — different agents can take different clusters at the same time.

Sizes

Triage estimates each sub-issue’s fix complexity as a size — S / M / L / XL (Small to Extra-large) — shown as a chip in the Backlog. A cluster’s chip is its largest member’s size.

Sizes drive model routing: a one-line copy tweak (S) doesn’t need the same model as a cross-file refactor (XL), and nitpin dispatches each at the model tier you’ve configured for that size.

Briefs

Along with sizes, triage records a short brief for each issue when it has something genuinely useful to add — a code-level hint (“the padding constant lives in CardStyle”) or a likely location. Briefs carry the triage pass’s understanding into the fix pass so the fixing agent starts warm. They’re advisory; your notes remain the spec.

Your corrections stick

Triage proposes; you dispose. Drag an issue out of a cluster (or into another one) and nitpin records it as an override — future triage passes keep your correction unless the backlog has genuinely changed around it.

Next: Running Triage · Splitting Issues

Running Triage

Triage runs in a coding agent — yours, launched for a few minutes with one job: organize the open backlog, then stop. There are three ways to start it.

From the Cockpit

Click Triage in the Backlog masthead. nitpin launches your configured agent headlessly, shows a “Triaging the backlog…” progress row (with a Cancel), tints the chrome slate-violet while it runs, and regroups the Backlog live as the clusters land.

Which agent and model run is set by the Triage row in Settings › AI Agents › Models.

From your coding agent

Type /nitpin triage in your agent (or ask it to “triage the nitpin backlog”). Same result, but interactive — you can watch it reason and answer questions. The agent reads the open issues, peeks at screenshots only where the text is ambiguous, splits anything incoherent, groups the rest, and stops without fixing.

From a terminal

nitpin triage --run                 # launch the configured agent headlessly
nitpin triage --run --harness codex # pin a specific agent
nitpin triage --run --only 3,5,8    # re-triage just these issues, merging in
nitpin clusters                     # print the current clusters

--only is a partial re-triage: the named issues are re-placed while every other cluster, override, and brief stays put.

When to re-run it

Triage isn’t one-shot — backlogs drift as you keep capturing. The auto-triage setting (per project, with a machine-wide default) watches the ratio of unclustered to clustered issues and recommends a re-triage when the pile outgrows the plan: Off / Suggest at 2× / 3× / 5×. Agents see the same recommendation and will re-triage before starting work when it’s warranted; your drag-corrections survive.

nitpin set autotriage=3     # the same knob, from a terminal

Splitting Issues

Sometimes one capture holds several unrelated problems — you froze the dashboard and pinned a typo, a broken chart, and a login bug. That’s three different fixes for three different parts of the codebase, and it shouldn’t travel as one issue.

During triage, an agent can split such an issue: every sub-issue is dealt into two or more new, focused issues, each with a sharp title of its own.

What a split does

• Each new issue keeps the same screenshot and provenance, with its share of the pins and regions — nothing you captured is lost or redrawn.
• Comments follow their sub-issue to the new issue it landed in; issue-level comments stay with the original.
• The original issue stays in the project as a breadcrumb: marked Split, off the open backlog, linking to its descendants — and each descendant links back. The lineage is always navigable in the Cockpit.
• The new issues then cluster like any others.

What a split doesn’t do

Splitting never fixes, resolves, or edits anything — it only reorganizes. And it’s deliberate by design: agents split only when sub-issues genuinely share no screen, component, or cause. A split is one-way (there’s no merge-back), which is why the bar for confidence is high — a coherent issue is always left intact.

How Agents Work Your Backlog

nitpin’s other half is the agent side: your coding agent reads captured issues over MCP, looks at the actual screenshots, fixes the code, and records what it changed. This chapter is the mental model; the following ones cover each piece.

The pieces

• The MCP server. The nitpin CLI doubles as an MCP server your agent starts automatically (it’s wired in by nitpin init per-repo, or nitpin install globally). It serves issues, screenshots, claims, triage, and resolutions — the full surface is in the MCP Tools reference.
• The skill. A nitpin skill teaches your agent the loop — when you say “check nitpin”, it knows to triage if needed, claim one cluster, look at the pins, fix, and resolve. See The nitpin Skill.
• Supported agents: Claude Code, Codex, OpenCode, and Pi. nitpin install wires any or all of them.

What an agent sees

When an agent opens an issue it gets your notes and body verbatim, plus focused imagery: a small crop around each pin or region — badges drawn on, so “the button #2 points at” is unambiguous — and a downscaled overview of the whole frame. It can ask for the full frame or the fully annotated render when it needs more context, and any images you pasted into notes ride along as part of the intent. Live captures also carry each mark’s CSS selector, which usually lands the agent in the right component in one hop.

What an agent does — and can’t do

An agent working your backlog will:

• claim what it’s working so other agents skip it (Claims),
• narrate — a one-line progress note you watch live in the Cockpit,
• fix one sub-issue at a time, each as its own commit,
• resolve each sub-issue with a short note (and the commit that fixed it), rating its own confidence so you know what to spot-check,
• comment when a note is ambiguous instead of guessing (configurable — see involvement),
• suggest out-of-scope improvements as pending issues for your review.

It can never edit your notes or screenshots, never resolves an issue wholesale (state rolls up from sub-issues), and — like nitpin itself — never drives your app.

Two ways to put agents to work

1. From your agent — type /nitpin or just talk to it. Best when you’re already in the terminal and want to watch. See The nitpin Skill.
2. From nitpin — click Fix on an issue or cluster, or run Autopilot over the whole backlog; nitpin launches and supervises the agents for you, routing each unit of work to the right model by size. See Dispatching Fixes and Task Models.

The nitpin Skill

The nitpin skill runs inside your coding agent, in a repo wired up with nitpin init (or a global nitpin install). It’s how the agent turns captures into fixes — and it responds to plain language as readily as to slash commands.

Fix the backlog — /nitpin

Type /nitpin with no arguments — or just say “check nitpin”, “any new issues?”, or “fix the QA feedback”. The agent:

1. Triages if needed — only when the backlog was never triaged or has drifted enough to warrant it.
2. Picks one cluster (or one closely-related issue) and claims it.
3. Looks at the screenshots — the focused crops of what each pin points at, your notes, and the discussion thread (your replies count as instruction).
4. Finds the code and fixes it, one sub-issue at a time, resolving each with a note and the commit.
5. Stops when that one logical chunk is done and summarizes.

One logical thing per session is the deliberate default — each change stays focused and reviewable.

Triage only — /nitpin triage

Organizes the backlog without fixing anything. See Running Triage.

Fix everything — /nitpin fix everything

Clears the whole open backlog, still one cluster at a time: triage first if needed, walk the clusters in priority order, then the ungrouped issues — batching the small stuff efficiently — and finish with a closing tally: what was fixed, what was declined and why, what was skipped, and any questions left in threads.

Fix a tag — /nitpin fix #ios

Fixes only the open issues carrying a tag you wrote in your notes (#ios, #dark-mode, #checkout). Say it naturally — “fix the #ios issues” works too.

Fix a specific bug

Reference an issue or sub-issue by number and the agent jumps straight to it: “fix issue #3”, “what’s sub-issue 2 on issue 5?”.

Binding

The skill acts on the project bound to the repo it’s running in — the .nitpin/ store inside the repo, or the project linked via nitpin link. If nothing is bound, the agent stops and asks which project to use rather than guessing; nitpin init or nitpin link fixes that permanently.

Claims & Parallel Agents

nitpin is built for more than one agent at a time. Claims are what make that safe.

How claims work

Before touching anything, an agent claims the issue (or cluster, or single sub-issue) it’s about to work. A claim is a short, self-renewing hold:

• other agents see it and pick something else — two agents never fix the same thing;
• it renews itself while the agent is alive, with no effort from the agent;
• it expires on its own within minutes if the agent dies — a crash never wedges the queue;
• resolving a sub-issue releases its claim automatically.

In the Cockpit, a breathing teal dot marks claimed work, with the agent’s name and its live progress line. If you want something back immediately — an agent looks stuck, or you want to fix it yourself — Stop agent in the Inspector releases the claim on the spot.

Worktrees: parallel by default

By default (How agents work → Parallel), every unit of agent work happens in its own isolated git worktree — a private checkout per agent. Your working tree stays untouched while agents work, and several agents genuinely run at once.

Prefer everything on your main checkout? Switch the project to One at a time (nitpin set worktrees=false): agents then work your checkout directly, and nitpin enforces a single agent across the whole project.

Landing: where fixes end up

The project’s Where fixes land setting decides what happens when a fix is done:

• Main — the agent lands each fix on your main branch. The default: captures simply become commits.
• Branch — the agent stops after committing to a review branch and tells you its name; you review and merge. Pick this when you want a look before anything lands.

nitpin set landing=branch is the terminal equivalent.

Progress you can watch

While an agent holds a sub-issue it keeps a one-line, present-tense note fresh — “aligning the pay button to the grid”, “running the tests” — replacing the line as its activity changes. That’s the line you see under claimed issues in the Cockpit and the popover, and it’s how a working agent and a hung one look different at a glance.

Dispatching Fixes

You don’t have to open a terminal to put agents to work — the Cockpit dispatches and supervises them for you.

Fix one thing

Every issue and sub-issue has a Fix action in the Inspector; clusters have Fix all. Plain Fix routes through your task models — the right model for the work’s size. Fix with ▸ opens a picker (agent → model → effort) when you want to choose by hand — say, escalating a stubborn fix to a bigger model.

Autopilot: fix everything

Autopilot in the Backlog masthead sweeps the whole open backlog (or, with a search active, just the matches — FIX MATCHES). Before committing you choose:

• Involvement — see below.
• Agent — Automatic (routed per unit by task model) or a specific one.

Then Fix all open N issues. Autopilot triages first if the backlog needs it, fans out one agent per cluster and per ungrouped issue, and batches small loner fixes into shared sessions (sweeps) so a dozen one-liners don’t cost a dozen sessions. How many agents run at once is capped by Settings › AI Agents › Parallelism.

While it runs, the verb becomes Running ⌄ with a live count; a progress bar in the rail tracks done / running / queued, and Stop all is one click.

Involvement: ask or auto

What should an agent do when a note is genuinely ambiguous?

• Async · ask (default) — park a question as a comment on that sub-issue, skip it, and keep working everything else. You answer in the thread; the next run picks it up.
• Async · auto — decide and keep going, unattended. For when you’d rather review diffs than answer questions.

The default lives in the project’s settings (When agents get stuck).

The roster

Click the presence cluster in the rail (or the running Autopilot verb) for Who’s working on what: every live agent, the sub-issues it holds (click to jump), its model and effort, a per-run Stop, and Stop all.

Watching the meter

Fixes report what they cost. During a run the status bar shows live token counts (↑ input · ↓ output); after it, each fixed sub-issue carries a small receipt — model, tokens, and a cost figure — in the Inspector. The menu-bar popover shows a running spend strip during big sweeps, so a glance tells you what the session is costing even with the Cockpit closed.

The same, from a terminal

Everything above is also a CLI:

nitpin fix 3                    # one issue
nitpin fix --cluster 2          # one cluster
nitpin fix --all                # the whole backlog (Autopilot)
nitpin fix --sweep 3,7,12       # batch small unrelated issues in one session
nitpin fix 3 --agent claude --model opus --effort high   # pin the routing
nitpin fix --all --involvement auto --max 4              # unattended, 4 at once

See the CLI reference for every flag.

Task Models

Not every nit deserves your biggest model. nitpin routes each unit of agent work to a model matched to the job — you configure the policy once in Settings › AI Agents › Models.

Five tasks, five preference chains

Each task owns an ordered preference chain — Primary › fallback² › … — of agent + model (+ effort) entries. Drag to reorder, Change model to edit an entry through an agent → model → effort picker, Restore default to go back to the shipped policy.

For each task nitpin tries the first entry whose agent is installed. Later entries are error fallbacks only — they run when the earlier one fails technically (API, billing, rate-limit, or auth errors), never because a fix was “hard”. Your primary is always the one doing the thinking.

Where sizes come from

Triage estimates each sub-issue’s size (S / M / L / XL); a dispatched unit routes by the largest size it contains. Work that was never triaged has no size — the Unsized fixes setting (default L) picks which chain it uses.

Explicit choices always win: Fix with ▸ in the Cockpit, or nitpin fix --agent/--model/--effort from a terminal, pin the exact routing for that dispatch.

Parallelism

Agents at once (Settings › AI Agents › Parallelism) caps how many fix agents Autopilot runs in parallel, machine-wide. Projects set to One at a time serialize regardless of the cap.

Reverting a Fix

An agent fixed it; you don’t like the fix. Revert fix surgically undoes that one change — without touching anything that landed after it.

From the Cockpit

Select the fixed sub-issue and choose Revert fix in the Inspector (nitpin confirms first). An agent is dispatched to:

1. Undo exactly that fix. Every resolved fix records the commit that carried it; the agent adds a new commit that reverses it — history is never rewritten, and later fixes are preserved. If the commit no longer reverts cleanly, the agent reconciles by hand; if it can’t do so safely, it stops and explains in the thread rather than guessing.
2. Verify the build and land the revert the same way fixes land (your landing setting).
3. Reopen the sub-issue — it returns to the open backlog with a plain-language note about what was reverted and why, and its stale fix metadata cleared.

While it runs you’ll see a Reverting… row on the sub-issue.

From a terminal

nitpin revert --issue 3 --sub-issue 1
nitpin revert --issue 3 --sub-issue 1 --model opus   # escalate the redo

Revert vs. Reopen

• Reopen just flips the status back to unresolved — use it when you rolled the code back yourself, or the fix never really landed.
• Revert fix does the git work too: undo the commit, then reopen.

After a revert, the sub-issue is an ordinary open item again. A common next move is re-dispatching it at a bigger model — Fix with ▸ and pick a tier up.

Tuning Your Project

Tune fits a project out for agentic work. A coding agent studies your source and your issue history, then assembles a Kit — review lenses, tools, skills, and a project guide — so every future fix lands like the agent already knows the codebase.

Open it from the menu bar (Tune Project…) or the Cockpit’s project menu. It’s the most thorough pass nitpin makes — it runs on your XLarge task model, takes a few minutes, and is worth re-running as the project evolves.

The wizard

Tune is one sheet that deepens through five steps:

1. Pre-flight — checks that a source repo is linked, the analysis agent is ready, and nothing else is running. Then Analyze (or Check for changes on a re-run).
2. Analyzing — the agent studies your stack, conventions, build commands, and the language of your captured issues. You can Hide the sheet and let it run in the background.
3. Review — your Kit. Every proposed piece appears as a row with a toggle, a plain-English description grounded in your repo, and a recommended tag where deserved. Switch off anything you don’t want, and use Add guidance on any row to steer how it’s built (“keep the context doc short”, “the UX reviewer should care about VoiceOver”).
4. Apply — the accepted rows install, top-down, with live per-row status. Generated pieces are validated before they’re installed; anything that can’t pass validation is skipped and says why.
5. Receipt — “your project is tuned”: what was installed, skipped, or failed, and where it all lives.

Re-running Tune reconciles rather than redoes: it proposes only what’s new or changed, and never silently overwrites something you’ve hand-edited since.

What’s in a Kit

• Reviewers (up to three) — project-specific review lenses the fixing agent runs over its own work: always a correctness lens, optionally a stack lens and a UX lens, each derived from what your issue history shows actually goes wrong. Reviews scale with fix size — trivial fixes skip review entirely — and are advisory: an unresolved objection lowers the fix’s confidence rating rather than blocking it.
• Tools — vetted, pinned developer tools wired into your agent (a code index, a memory runtime, language-server wiring), drawn only from nitpin’s curated catalog.
• Skills — pinned skills for your stack from the official skills registry.
• Context — a project guide: what the app is, the architecture in brief, verified build and test commands, conventions, your vocabulary, and known sharp edges.
• Rubric — what S / M / L / XL actually mean in this repo, so triage sizing matches your reality.

An always-on extra rides along: a terse register that trims agents’ scratch output so dispatched runs spend fewer tokens on narration.

Just for you, or the whole team

On first run you pick where the Kit lives:

• Just for you — stays on this machine; nothing is committed.
• Share with your team — the Kit’s files are committed to your repo so teammates (and their agents) get the same setup. The receipt shows exactly which files were committed — review the diff before you push.

Sync Issues with Git

An in-repo project’s issue store is just files in .nitpin/ — which means git can carry your captures to teammates, other machines, and CI, with nitpin doing the commit-and-push chores for you.

What syncs

When a project is linked to a git repo with a remote, nitpin keeps the issue store in sync: your issues, screenshots, notes, comments, and resolutions. Two per-project choices in Project Settings › Issue Sync shape it:

• Where the store syncs — nitpin/issues (default: issue commits stay off your main branch on a dedicated branch) or main (issue commits ride along with the code). This is independent of where code fixes land.
• Share triage groups — whether the triage clustering syncs too, or stays local.

Claims always stay local — which agent on your machine holds what is never anybody else’s business.

The sync pill

The Cockpit’s status bar shows sync at a glance: a calm check at rest, ↑ N when commits are waiting to push, Saved when you’re offline (everything is committed locally and pushes when you’re back), and Sync error when something needs a look. Tap it to Sync now.

From a terminal:

nitpin sync            # commit, pull, push — the full round trip
nitpin sync --push     # commit + push only
nitpin sync --pull     # pull only

Joining a project from a repo

If a teammate’s repo already carries a .nitpin/ store, you don’t set anything up:

nitpin clone https://github.com/team/app     # clone + open its project in one step

— or use New Project… › Clone from Git in the app. Cloning an ordinary repo without a store creates one for it.

Trust, exactly bounded

nitpin’s git behavior is deliberately narrow, and enforced in code — not by convention:

• it stages only the .nitpin/ store — never your code;
• it only ever runs add / commit / fetch / pull –rebase / push (and non-destructive worktree bookkeeping); it never force-pushes, resets, cleans, or rewrites history;
• its work happens on a hidden checkout, never your working branch — a sync can’t disturb what you have open;
• it stores no credentials, riding your existing git setup (SSH agent, credential helpers).

Code fixes are different: those commits are made by your coding agent under the project’s landing setting, not by nitpin.

Settings

nitpin’s settings live in two places: the Settings window (⌘, — machine-wide, three tabs) and the per-project Project Settings popover in the Cockpit.

Settings › General

System

Capture

Record any combination; nitpin warns if another app already owns it. Shortcuts work system-wide while nitpin is running — capture is paused while Settings is open.

nitpin — the update section: current version, Check Now, one-tap Install Update (download → verify → relaunch), and a collapsible What’s new.

Settings › AI Agents

Coding agents — the roster of supported agents (claude, codex, opencode, pi), each shown as Available (with its models), Detected (one-click Set up), or Not installed. nitpin wires itself into agents you have; it never installs one.

Models — the task-model routing: one preference chain per task (Triage / Small / Medium / Large / XLarge), each an ordered list of agent + model + effort entries. The first available entry runs; later entries are fallbacks after technical errors only. Plus Unsized fixes — which size chain (S/M/L/XL, default L) handles work triage hasn’t sized.

Parallelism — Agents at once: the machine-wide cap on parallel fix agents.

Settings › Projects

Machine-wide defaults inherited by new projects (each project can override them — see below):

Project Settings (per project)

Anchored to the Cockpit’s title — the settings of this project:

• Name — rename the project.
• Source — the linked code folder and its origin repository (linking itself is done from the repo: nitpin link).
• Issue Sync — where the issue store syncs (a dedicated nitpin/issues branch, or main) and whether triage groups are shared. See Sync Issues with Git.
• How agents work / Where fixes land / When agents get stuck / Auto-triage / Resolved issues shown — this project’s values for the workflow defaults above.
• Delete this project… — moves the project’s store to the Trash (with a confirmation).

The scriptable subset is also settable from a terminal:

nitpin set worktrees=false          # one agent at a time
nitpin set landing=branch           # fixes land on a review branch
nitpin set defaultInvolvement=asyncAuto
nitpin set autotriage=3
nitpin set resolvedIssueLimit=200

CLI Reference

The nitpin command wires repos to projects, launches agents, and syncs stores. It’s also the MCP server your coding agent talks to (started automatically — you never run that part yourself).

nitpin <command> [options]
nitpin --help            # list commands
nitpin --version

Commands act on the project resolved from your current directory: the repo’s .nitpin/ store, or its nitpin.yaml link, or — outside any repo — the app’s active project. Many commands accept --project PATH to target another project explicitly.

Setup

nitpin init [name] [--path PATH] [-y]

Set up nitpin in this project — creates the issue store and wires up your coding agent.

Creates ./.nitpin/ (the store), .mcp.json, and the agent skill. Safe to re-run: an existing store is never touched; drifted wiring prompts before updating (or updates silently with -y). Restart your coding agent afterwards so it picks up the MCP server.

nitpin install [harness] [--quiet] [--force]

Install nitpin into your coding agents, user-globally (alias: nitpin setup).

With no arguments, an interactive wizard shows every detected agent — check to install, uncheck to remove. Re-runs skip agents that are already current.

nitpin uninstall [harness] [--quiet]

Remove nitpin from one coding agent, or from all of them with --quiet.

Projects

nitpin open [path]

Open the project for path (default: the current directory) in the nitpin app and make it the active project.

nitpin projects

List the projects nitpin knows about, with their paths.

nitpin link [target]

Use an existing nitpin project for this repo. target is a project name or path; omit it to pick from a list. Writes the repo’s nitpin.yaml pointer.

nitpin unlink

Stop using the linked project in this repo (removes the pointer). A store living inside the repo can’t be unlinked — it travels with the repo.

nitpin clone <url> [dest]

Clone a git repo and open its nitpin project in one step. If the repo already carries a .nitpin/ store you join it; if not, one is created. dest defaults to a nitpin- managed clones folder.

nitpin set <key>=<value>

Set a project setting from the terminal (the same knobs as Project Settings):

The backlog

nitpin status

This project’s dashboard: issue counts by state, sub-issues still open, the triage picture (with a re-triage recommendation when warranted), and which coding agents are available.

nitpin list [--state STATE]

List the project’s issues — number, state, title, and sub-issue counts. --state filters to one of unresolved, in_progress, resolved, wont_fix, split.

nitpin clusters

Print the current triage clusters — labels, summaries, members — and your overrides.

Agents

nitpin triage [--run] [--harness ID] [--only N,N,…] [--project PATH]

Group the open issues into clusters, running your coding agent headlessly.

nitpin fix [ISSUE] [options]

Fix sub-issues with a coding agent: one issue, a cluster, a batch, or the whole backlog. Exactly one scope is required:

Each unit routes through your task models by its triage size; --agent/--model/--effort pin the routing instead.

nitpin revert --issue N --sub-issue M [options]

Revert one landed fix and reopen its sub-issue, keeping every later fix. See Reverting a Fix. --agent / --model / --effort pick who does the reverting; --sub-issue 0 is the issue’s body.

Sync & maintenance

nitpin sync [--push|--pull] [--project PATH]

Sync the project’s issue store with its git remote — commit, pull, and push (or just one direction). See Sync Issues with Git.

nitpin update

Update a standalone (curl-installed) nitpin CLI to the latest version. A CLI that shipped inside the app defers to the app’s updater.

nitpin migrate <path> [--check] [--json]

Bring an older project store up to this nitpin’s format. --check reports what would happen without changing anything; migrations back the store up first. You’ll rarely need this — stores from recent versions read in place.

Environment variables

Plumbing

Two commands exist for machinery rather than people: nitpin mcp runs the MCP server (your coding agent starts it automatically), and nitpin release <issue> force-drops every claim on an issue — the terminal escape hatch when an agent died mid-work (the Cockpit’s Stop button does the same thing with a click).

MCP Tools

Coding agents talk to nitpin through the nitpin MCP server — wired in by nitpin init (per repo) or nitpin install (user-global) and started automatically by the agent. This page is the tool surface, for the curious and for anyone building their own agent integration.

The server resolves its project from the directory the agent runs in — the repo’s .nitpin/ store, its nitpin.yaml link, or the app’s active project — so the same tools work in any wired repo.

Reading issues

Resolving

Claims & progress

Claims renew themselves server-side — agents never heartbeat — and expire on their own if an agent dies. In a one-at-a-time project, the server grants nothing while any other agent holds a claim. See Claims & Parallel Agents.

Triage

Tune

propose_kit(suggestions) and record_kit(artifacts, failed?) are the write channel of the Tune wizard’s analyze and apply passes. They’re bound to the app’s running Tune session — an agent can only call them when the wizard dispatched it — so they’re not part of the general agent surface.

Guides

Where Your Data Lives

nitpin is local-first: everything you capture is plain files on your machine — YAML and PNGs you can read, diff, and version like anything else. No backend, no cloud copy; screenshots, notes, and repo paths never leave your device.

A project store

A project is a folder:

.nitpin/                        (or a folder under ~/.nitpin/projects/)
  project.yaml                  the project's identity and settings
  issues/
    001_pay-button-misaligned/
      issue.md                  the issue — your notes, statuses, provenance
      clean.png                 the capture, untouched
      annotated.png             the capture with badges drawn (when marks exist)
      img-1.png                 any images you pasted into notes or comments
      comments.yaml             the discussion thread (when there is one)
  locks/                        transient agent claims (never committed)
  clusters.yaml                 the triage grouping (committed only if you share it)

Screenshot pixels are never embedded in text files — images sit beside the issue as ordinary PNGs. An in-repo store is meant to be committed: issues travel with the code, and git sync automates the chore. Claims and other transient state are ignored by git automatically.

The user store

Machine-wide data lives in ~/.nitpin/:

~/.nitpin/
  config.yaml            machine-wide preferences (default project path, task models, …)
  projects.yaml          the list of known projects
  active-project.yaml    which project captures land in
  projects/              "in nitpin" project stores

Set NITPIN_HOME to relocate all of it.

How a repo finds its project

Tools and agents resolve the project for a directory in this order:

1. a .nitpin/ store in the directory (or an ancestor),
2. a nitpin.yaml pointer written by nitpin link or nitpin init --path,
3. otherwise, the app’s active project.

Portability & backup

Because a store is just files: back it up by backing up the folder, move it by moving the folder, share it through git. Deleting a project from the Cockpit moves its store to the Trash — nothing is ever destroyed silently.