How discern works

discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your project. lets you hand coding agents substantial work, and keep several tasks moving at once, without coordinating every step or explaining your project again each session. Each finished change comes back with a record of which of your project's commands passed, so you don't have to take an agent's word that the tests ran.

Your project also gets better as the work goes on, because each gain you lock in holds for every change that follows.

Each part of the job has one owner, so your time goes into the decisions only you can make.

• You set the direction, try what comes back, and decide what lands.
• Your agent does the work and runs discern for you, so you don't need to learn discern's commands.
• discern runs your project's own commands, records which passed, and lands a change on your shared branch only with your permission. It has no AI model of its own, so the thinking stays with your agent.

Say people using your reading-list app want to find a book without scrolling. You ask your agent:

"Add search to the reading list, so people can find a book by title or author. Show me how to try it, and tell me what you checked before I decide whether it lands."

Your agent makes the change in a worktree, a separate copy of the project on its own branch, so your shared branch, the trunk (usually main), stays untouched while it works. Several agents can work at once, each in its own worktreeWorktree↗A separate copy of your project, on its own branch, where one task's work happens.. Running discern in your project folder opens the desk, a view in your terminal that shows which tasks need your decision.

When the search works, your agent commits it and runs the gate: your project's own commands, such as its linter and tests, which must all pass before a change counts as finished. When they pass, discern records Proof of which commands passed on that exact commit, the saved version of the code they ran on. Your agent's report ends with a line like this:

Proof: GateGate↗The full set of checks your project requires before a change counts as finished. passed for agent/reading-list-search-4e1f2a at 9b3c71d0e5a2 · 4 files changed (+96 −8) vs main · View the full Proof: discern status --verbose

A pass means those commands passed on that commit, and nothing more, so whether the search helps people is still your call. You try it: "Le Guin" brings up her novels, but a search with no match leaves the page blank. You ask for a short message instead. Your agent adds it in the same worktree and runs the gate again, because any later edit makes Proof stale. Proof explains how to read the line.

When you're satisfied, you say "land it". discern checks that the Proof is current and that your permission covers the change. Then the search lands: it joins the trunkTrunk↗Your project's shared branch, usually main, where finished changes land.. If another task landed first, discern checks the two changes together and lands exactly what passed, so the search doesn't go back to the start.

Agents can add code faster than anyone can read it, so quality can slip in steps too small to notice: a skipped test, a slightly larger download, a fixed bug that comes back. discern turns each improvement into something later work has to keep.

• Quality limits only tighten. A standard is a measured limit your project holds, such as its test coverage or download size. No change can loosen it without your approval. When a measure improves, you can lock in the new level for every change after it.
• Fixed bugs stay fixed. discern's bug-fixing skill, a playbook your agent follows for that job, has it find the real cause, fix every instance, and add a test or lint rule that fails if the bug comes back.
• Lessons carry forward. Say you decide the reading list must work offline. Your agent writes that rule into the project's instructions and adds a test for it, so every later agent reads the rule and every later change has to pass the test. The reason goes into the map, your project's guide to how it works, which your agents keep current, so you can see what they understand.

Because your agent runs discern, discern treats the agent as its main user, so each result is short and names the next step. A failing test comes with its output and a command that reruns it on its own, so your agent goes straight to the cause. For common jobs, such as splitting big work into tasks, your agent has a skillSkill↗A ready-made playbook that tells your agent how to handle a particular kind of task. to follow, and discern's documentation search returns the few pages a task needs.

That leaves more of your agent's context, the limited amount it can hold in mind at once, for understanding and changing your project. For you, it means less time unblocking your agent, and more of its effort in the work you asked for.

A setup session. Your agent studies the project, connects its existing commands to the gate, and writes the instructions and mapMap↗Your project's own guide to how its software works and why, which your agents write and keep current. that later sessions use. Expect 20 to 40 minutes of agent time and a meaningful number of tokens. You answer what only you can, such as what the project is for, and review the setup before it lands.

Time to review. For a small change you can see, trying it and reading the Proof is often enough. When a change touches something you can't judge yourself, such as security, ask for an independent review.

discern is for people who build with a coding agent, and it helps most when you want agents to take on bigger pieces of work. It works with any language and tools, because it runs the commands your project already uses. It needs Git, which your agent offers to set up if your project doesn't use it yet. One setup covers a whole repository, even one that holds several apps.

It supports Claude Code, Codex, Gemini, Cursor, and GitHub Copilot, on macOS, Linux, and Windows through WSL 2. discern writes the same project instructions into the files each of those agents reads, so your rules come with you when you switch agents. Platforms and providers has the details.

It runs on your machine. discern is one program: there's no account, API key, or service to set up. Its local record of what its commands did holds metadata such as timings, never your code or command output, and you can turn it off. discern doesn't sandbox your agent, so your agent's own settings decide what it can read and run. Your agent still uses its own model provider, and your project's commands can still reach the network. What stays on your machine explains more.

Nothing lands without your permission. A passing gate never grants it. You approve each change yourself, or pre-approve routine areas, such as documentation, and everything else comes back to you. No pre-approval covers a looser limit or an unmet answer to a checkpoint, a review question your agent answers when a change touches certain files. Those need your decision each time. Landing isn't releasing, either: shipping to your users stays with your own release process.

Your files stay yours. What you and your agents write stays in ordinary files in your repository, and discern uninstall keeps them when it removes discern's wiring. discern never updates itself, so you choose when to upgrade. discern is Fair Source software, and what it adds to your project, such as its built-in instructions and skills, comes under the Apache 2.0 license. Maintain or remove discern and Licenses have the details.

To try it, install and set up discern. To go deeper, read about Proof, worktrees, checkpoints, standards, and instructions, skills, and the map.