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.