Threshold v0.1.0

The guide

How to install Threshold, read a review, talk it through with the agent, and give your verdict.

01What Threshold is

Threshold is a desktop review inbox. A change arrives as a review: the diff cut into chapters, in the order that explains it rather than the order git emits it. The idea comes first, then what follows from it, then the mechanical edits, labelled as such. A brief up front says what the change is and what it implies. Flags mark the few lines that matter. You leave notes on any line, and the answers come back in a thread on that line.

The chapters are written by an agent that understands the change, and there are two ways that happens:

Your agent's own change. It has finished something wide-reaching, commits it to a branch, and hands it to you before it lands. It stays on the other end: your questions get answers, your objections get revisions, and the review ends with your verdict.
Someone else's PR. You point an agent at a colleague's branch. It reads the change and hands it to you as a review, with a brief, chapters and flags (chapter 8).

Threshold is a desktop app because the work it shows you is on your machine: the agent runs there, and the repository is there. Threshold reads the diff from your checkout with git, so nothing is uploaded anywhere. The agent and Threshold talk through a file in ~/.threshold/reviews/. Any agent that can run shell commands can write one, and there's nothing else to set up. Because a review is a file instead of a protocol, agents can send reviews even when the app isn't open, and you can do your reviews even when no agent is actively listening.

02Installing

Download the build for your machine and drag Threshold into Applications.
Open it once. The builds aren't notarized yet, so macOS stops the first launch with "Apple could not verify Threshold is free of malware", and offers only Done and Move to Trash. That's expected:
1. Click Done.
2. Open System Settings → Privacy & Security and scroll down to Security. It says Threshold was blocked, with an Open Anyway button.
3. Click Open Anyway, confirm with your password or Touch ID, then choose Open.
The button only shows for a while after a blocked launch. If it isn't there, open Threshold again, click Done, and go back. You only do this the first time.
Leave it running. It's an inbox: it's most useful when it's already open when a review arrives.
Give your agent the threshold-review skill (chapter 3). It tells the agent how to write a review.

03Hooking up an agent

The agent's half of Threshold is the threshold-review skill: one Markdown file that tells an agent when to ask for a review and how to write one. It covers the brief, the bundle, flags, reading Threshold's diagnostics, answering your notes, revising, and acting on your verdict.

Claude Code

Until your first review arrives, Threshold's main pane has an Install for Claude Code button. It copies the skill into ~/.claude/skills/threshold-review/. From a clone of the repository, you can copy it yourself:

mkdir -p ~/.claude/skills/threshold-review
cp skills/threshold-review/SKILL.md ~/.claude/skills/threshold-review/

Then ask for it the way you'd ask a person: "review this in Threshold", "let me approve this first", "show me the diff before you push". The skill also tells the agent to reach for Threshold on its own before anything destructive or wide-reaching.

Any other agent

Give it the contents of SKILL.md. There's no SDK, server or API to install. An agent that can run shell commands, append a line to a file and read one back can use Threshold.

whenThe skill tells agents to use Threshold for changes that are hard to reverse or too large to judge from a sentence, and not for small fixes.

04The inbox

Every review lives in ~/.threshold/reviews/ as one file. The inbox lists them, newest first, under the name the agent gave the file: a date and the repository, like 2026-10-27-143005-stacks. A count shows how many are waiting on you.

The agent will also say in chat that a review is waiting, and name it. If Threshold isn't running, the agent says so rather than launching it: the review waits in the folder until you open the app.

Reviews you're done with can be archived. History shows every past verdict and what it was about.

05Reading a review

Start with the brief

The brief comes before any code: a title, a summary, and the implications. These are what's irreversible, what will fail loudly, and what the agent couldn't check. Read it the way you'd read a colleague's note on a pull request. It tells you where to point your attention.

Narrative or files

The narrative is the agent's chapters, in the order that explains the change: the idea first, the mechanical call-site edits last, labelled as such. The files view is the plain per-file diff git would give you. Toggle between them whenever you like.

Threshold checks that every hunk is in some chapter and shows the count, 13 of 13 hunks in a chapter. If any are missing, the count turns red, the missing hunks get a section of their own, and the narrative won't open as the agent's story at all.

Flags

Before you've read anything, the agent can mark the lines it thinks matter:

flag	means
attention	The load-bearing line: the decision everything else follows from.
caution	The risky one: irreversible, or the most likely to be wrong.
context	Looks odd, isn't. Saves you a question.

Each flag quotes the line it's about. If the quote doesn't match the line it lands on, Threshold drops the flag. Code the agent never looked at doesn't get a confident pointer.

Markdown and images

A changed Markdown file is rendered, with the changed blocks marked and its relative images shown inline. A design doc and its figures read together. Changed images are shown before and after, side by side.

The facts

At the top: files and lines changed, whether anything is deleted, and whether a test file is touched.

06Discuss

Comment on a line, on a chapter, or on the review as a whole. The agent is watching the same log, and replies in a thread under your note.

If your question finds something, the agent fixes it, commits, and posts a revision. The diff on screen moves to the new commits, and a fresh narrative follows. Notes left on older code say so instead of quietly re-attaching to whatever line now sits there. A note follows its line through an amend when the line is still there.

As you go, mark chapters you've been through. A mark records progress, not approval.

07The verdict

Approve or Reject. A rejection needs a reason, and the agent treats that reason as its next instruction.

Either verdict carries the SHA-256 of the diff that was on your screen, so the agent can prove your approval is about what it's about to ship:

git diff main...HEAD | shasum -a 256   # must equal the verdict's digest

A verdict is the end of a review, unless the agent revises after it. Then the review goes back to waiting on you.

Every verdict is also written to a permanent decision log alongside the reviews: a plain, append-only record of what was decided, about which revision, with its digest.

08Other people's changes

An agent can also write a review of a colleague's PR. Ask it:

Read PR 214 (branch feature/cover-storage) and hand it to me in Threshold.
Chapters in the order that explains it, flags on what I should look at,
and tell me what you couldn't work out from the code.

The agent fetches the branch, reads it, and writes the review for a range such as main...origin/feature/cover-storage. The review pins to those commits like any other. You read it, ask the agent about anything, and take what you've learned back to the PR.

the differenceThe agent didn't write this change, so it can explain it but not revise it. Its brief is a reading, not the author's intent: where it says it couldn't work out why, that's a question for the author.

With no agent at all

Threshold also works as a plain diff reader. Open any repository and review its working tree, its staged changes, or a revision such as main...HEAD. There are no chapters without someone to write them, but pinning, the facts, Markdown and images all still apply.

09Pinning

A revision spec like main...HEAD is a question, not a thing. Ask it again after the agent commits, or after someone moves main, and you get a different answer. A review that re-ran git diff every time you came back would show a different change each visit, silently.

So when a review lands, Threshold resolves its spec once, to the two commits git would compare, and diffs those from then on. Two object ids name exactly one diff forever. You'll see this in the header: pinned 3f9e1c2..a71d0b4.

unpinnedSome specs can't be pinned. HEAD~3 or a bare diff compares against the working tree, so half of what you see is whatever is on disk right now. Those reviews still open, with a warning across the diff, and Threshold tells you if the diff moves while you're reading. Ask the agent to commit and hand over a range.

10When something looks off

you see	it means
The hunk count is red	The agent's narrative leaves something out. The missing hunks are listed in their own section. Ask the agent for a complete bundle, or read them in the files view.
A warning across the diff	The review isn't pinned and part of it is the working tree. Ask for a committed two-commit range.
A note says it was made on older code	The agent revised since. Check whether the line you asked about still says what it said.
A flag you expected isn't there	Its quoted text didn't match the line, so Threshold dropped it.
The phone says the Mac isn't there	Threshold isn't running on that Mac, or Tailscale is off on one side.
Nothing ever arrives	The agent doesn't have the skill, or is writing somewhere other than `~/.threshold/reviews/`.

Problems with what the agent sent are also written into the log as diagnostics, addressed to the agent, so it can usually fix them before you get that far.

11Your phone

Threshold can serve your reviews to your phone over Tailscale. From the phone you can read, ask, mark chapters, and approve or reject. It notifies you when an agent has said something you're waiting on.

Run the phone setup script from the Threshold repository: scripts/threshold-mobile-setup.sh. It installs Tailscale if needed and asks what to call this Mac.
That name becomes the Mac's tailnet address, the home-screen label, and the coloured band across the top of every phone screen, in the colour you pick. Give each Mac its own name and colour.
In Threshold, open Phone and scan the code with your phone's camera. Add the page to your home screen.

The code works once, for one minute. Phones paired from the Mac can be revoked there. The phone works only while Threshold is running on that Mac, and it says so when it isn't. scripts/threshold-mobile-setup.sh --off turns it off.

guarantee	how
Never on the public internet	Threshold listens on 127.0.0.1 only; `tailscale serve` puts it on your tailnet over HTTPS.
A phone verdict is about what it showed	It names the diff it read and is refused if that diff has changed since.
Only your phones	Every request carries a device credential from pairing.
The right Mac	Every write names the machine it's meant for; a write that reaches a different Mac is refused.
Private notifications	Encrypted end to end (RFC 8291); the push service relays them unread.

12The session log

A review is one append-only JSONL file, the session log. The agent writes to it, Threshold writes to it, and both watch it. Nothing else connects them. Each line is one complete event:

{"seq":1,"at_ms":1757255400000,"from":"agent","revision":"main...HEAD","kind":"brief",
 "repo":"/path/to/repo","title":"Move book covers into storage","summary":"…",
 "implications":["Irreversible without a restore","…"]}

seq is one greater than the highest in the file. from is agent, human or threshold. revision records which version of the change the event was written against.

kind	from	what it is
`brief`	agent	What the change is and what it implies. Opens the review and names the repo.
`bundle`	agent	The narrative: chapters of hunks in the order that explains the change.
`note`	either	A comment on a line, a chapter or the whole review. An agent's note with a `flag` marks a line.
`reply`	agent	An answer to a note.
`revised`	agent	The code changed; the diff under review moves.
`pinned`	threshold	The review's revision resolved to two commits.
`diagnostic`	threshold	A problem with what the agent sent.
`chaptermark`	human	The reviewer has been through a chapter. Progress, not approval.
`verdict`	human	`approved` or `rejected`, with a reason and the digest of the diff on screen.

Because it's a file, you can read any review with cat, and it survives a restart on either side.

13Building from source

Threshold is a Tauri app: a Rust core and shell with a TypeScript UI. You'll need Rust, Node, and Tauri's platform prerequisites (on Linux, the WebKitGTK libraries).

cd app
npm install
npm test            # the UI's pure logic
cargo test          # the diff parser, logs, pinning, the phone server
../scripts/build-git.sh   # the git the app carries (THIRD_PARTY_NOTICES.md)
npm run app:build   # bundles land in target/release/bundle/

On a Mac, scripts/install.sh builds and installs it into /Applications, and scripts/install-hooks.sh keeps it current as you pull.

The source is MIT-licensed, and the repository is on GitHub.