The discern manual

discerndiscernA tool that lets you hand real work to coding agents and still decide what joins your project. lets you hand coding agents substantial work, such as a whole feature, without coordinating every task yourself, explaining your project again each session, or taking an agent's word that the tests passed. Your project also gets better as the work goes on, because each gain you lock in, such as higher test coverage or a smaller download, holds for every change that follows.

Your agent runs discern for you, so this manual covers your side of the work: asking for what you want, reading what comes back, and deciding what joins your project. If you're still deciding whether discern fits, start with How discern works.

Start here

Install and set up discernInstall discern, have your agent set up your project, and review what every later session will inherit before it lands.
Delegate substantial workTurn a big idea into tasks that fresh agents can carry on their own, then review what comes back.
ProofSee which of your project's commands passed on the exact commit you're reviewing, what that leaves for you to judge, and who decides whether it lands.
Instructions, skills, and the mapTeach your agents something once, and every later session starts out knowing it, whichever coding agent you use.
TroubleshootingFind the page for what went wrong, keep unfinished work safe, and take the next step to recover.

Find your next task

Ask your agent in your own words. Each guide shows what your agent does with the request and what to look for in what comes back.

What you want to do	Where to begin
Review a change and add it to your project.	Finish and land a change
Keep several tasks moving at once.	Coordinate parallel tasks
Stop a hard-won improvement from slipping back.	Set and raise standards
Have your agent answer a review question when certain files change.	Place and answer checkpoints
Pick up a task after a session ends.	Recover an interrupted task
Give your agents a reusable method for work that repeats.	Create and manage skills

Understand explains the ideas behind discern, and the guides put them to work on everyday tasks. Reference has the exact commands, settings, supported coding tools, and formats.

Read it anywhere

Search the manual at discern.sh/docs, or run discern docs to read it offline in your terminal. There, press / to search, Enter to open a page, and q to close the reader. Your agent reads the same pages through discern_docs, so you and your agent work from the same text.

Add .md to the end of a page's web address to get its raw Markdown. The CLI reference covers the reader's other keys, opening a page directly, raw output, and paging.

See discern at work on itself

discern is built with discern. Its agents work in the same separate workspaces and hold the same kind of quality limits discern sets up for your project. Before a change lands, they run the project's formatter, linter, type checker, and tests. The map of the codebase those agents keep shows the project knowledge they work from, and the decision records explain why the product works the way it does.

Start

Decide whether discern fits, have your agent set it up, and review your first change.

How discern worksDecide whether discern fits your project, and see who does what as a change goes from your request to your shared branch.
Install and set up discernInstall discern, have your agent set up your project, and review what every later session will inherit before it lands.
Make and review your first changeAsk for a small change, try it, see what was checked, and decide whether it joins your project.
After setupSee what each file setup added is for, check what later sessions will inherit, and know where to make changes later.

Understand

Learn what a finished change has passed, what your project keeps for the next task, and which decisions stay with you.

ProofSee which of your project's commands passed on the exact commit you're reviewing, what that leaves for you to judge, and who decides whether it lands.
Worktrees and trunkLet each agent build, break, and fix things in its own copy of the project, while your shared branch moves only when a change you've approved lands.
CheckpointsHave the review questions that need judgment asked whenever a matching change happens, with your agent's answer in the Proof.
StandardsLock in a measured improvement so every later change has to keep it, and decide for yourself when a limit should move.
Instructions, skills, and the mapTeach your agents something once, and every later session starts out knowing it, whichever coding agent you use.
What stays on your machineSee what discern runs, records, and writes on your machine, and where your coding agent and your own commands go beyond it.

Guides

Find the guide for what you want to get done, from landing a change to keeping what your project learns.

Finish and land a changeReview a finished change, ask for fixes, and land it on your shared branch, even when other work has landed first.
Land an urgent repairLand a fix before its tests and other checks finish, see exactly what you're skipping, and settle those checks afterwards.
Fix a red gateHand a failing test or linter to your agent, know which decisions are yours, and recognize when the change is ready again.
Recover an interrupted taskPick up an unfinished task in a new session, read back a run you lost track of, finish a landing that stopped partway, or restore work from a dropped branch.
Delegate substantial workTurn a big idea into tasks that fresh agents can carry on their own, then review what comes back.
Coordinate parallel tasksKeep several agents working at once, see which tasks need your decision, and land their results in the order you choose.
Wait for another taskLet an agent carry on as soon as the work it needs from another task is ready, without you passing messages between them.
Write project instructionsTell your agent a rule once, and every later session starts with it, in every coding tool your project uses.
Maintain the project mapKeep a current, readable account of how your project works, so each new agent starts from it and you can correct a wrong assumption early.
Create and manage skillsUse discern's ready-made skills, and give your agent your own tested methods that every later session and coding tool can reuse.
Set and raise standardsLock in a measured gain so later changes can't give it back, and decide for yourself when a feature is worth a looser limit.
Place and answer checkpointsName a review question once, and your agent answers it on every change it applies to, before you review.
Improve how your agents workFind the change that would help your agents most, based on what happened in past tasks, then try it and see whether it helped.
Connect a coding agentAdd a coding tool to your project, and it starts with the same instructions and skills as your other tools, and its changes face the same tests and linters.
Use discern alongside other agent toolsKeep another tool's agent rules, skills, and settings working beside discern's, so neither tool undoes the other's files.
Run the gate in CIRun your project's own checks on your code-hosting service, so a change that only breaks on another system is caught before it merges.
Maintain or remove discernDiagnose, tidy, and upgrade discern in your project, or remove it and keep everything you wrote.

Reference

Find the exact answer about any discern command, setting, supported coding tool, file, or result.

GlossaryLook up discern terms, understand their meaning, and find the next useful explanation.
CLI referenceFind discern commands and options, understand their results, and use the terminal documentation reader.
Config referenceFind what each discern.toml setting does, which values it accepts, and what happens when you leave it out.
Environment variablesLook up the DISCERN_* settings you can supply and the values discern passes to project commands.
Platforms and providersCheck which computers and coding tools discern supports, what each one needs, which files discern writes for it, and how to confirm that it loaded discern.
Files and ownershipLook up which files you can edit, which files discern maintains or rebuilds, where it keeps local records, and what uninstalling leaves behind.
LicensesSee which license covers the material discern adds to your project, which covers discern itself, and what to keep when you redistribute it.
Worktrees and statusLook up what discern status reports about each task, what every status field means, and the identity and environment values each worktree gets.
Proof and checkpoint formatsLook up the exact format of a Proof note, the worktree's Proof marker, the states of a checkpoint question, and the protocol for a checkpoint's when command.
LogbookLook up what discern's local logbook records, what reads it, how to read its reports and stats, and how to archive or reset its history.
MCP and resultsLook up the tools discern gives your agent, what each one accepts and returns, and the exit codes and schemas behind its results.
CompatibilityWhat stays the same when you upgrade discern, what can change, and how a schema you pinned keeps working.

Troubleshooting

Find the page for what went wrong, keep unfinished work safe, and take the next step to recover.

Setup and integrationsFinish installing discern, carry on with a setup that stopped partway, and get your coding agent connected.
Gate and ProofFind out why the gate stopped or gave no Proof, fix the cause, and know which decisions are yours.
Worktrees and resourcesFind out why a task won't land or won't clean up, or why its app uses the wrong settings, and fix it without losing work.
MCP, terminal, and docsGet your agent's discern tools back, keep a wait going, read a result you missed, and open the page you need, without running anything twice.
Crashes and local statePick up your task after discern crashes, send a useful report, and find out what a discern file holds before you delete it.