Maintain or remove discern

Keep discerndiscern↗A tool that lets you hand real work to coding agents and still decide what joins your project. healthy and current in your project, or take it out, without losing anything you wrote. Your agent does most of the work. Your instructions, skills, and mapMap↗Your project's own guide to how its software works and why, which your agents write and keep current. belong to your project, so they stay when you upgrade, and they stay if discern goes.

When a discern command or a coding tool's connection stops working, ask:

"discern has stopped working. Check the installation, fix what you can, and tell me what you need from me."

Your agent runs discern doctor, which changes nothing and names a fix for each problem it finds. The agent explains what it found, applies the fixes, and runs doctor again. A clean run covers the installation, and a repaired connection also needs a new coding-tool session. Troubleshooting matches common symptoms to their fixes.

If your instructions, map, or discern.toml get hard to read, ask:

"Tidy up the formatting of the files discern manages, and bring the changes back for review."

The agent previews, then formats, in its worktree, a separate copy of the project:

discern tidy --dry-run
discern tidy

Tidy formats your instruction sourcesInstruction source↗The file where your project writes its own instructions for coding agents., the map, the work ledger (discern/TODO.md by default), and discern.toml, and leaves your code, skills, and generated filesGenerated file↗A file discern builds for your coding agents: an agent file or a skill folder. to your project's own formatter. If a file can't be parsed, tidy changes nothing until the agent fixes it.

The agent reviews and commits the changes, then runs the gate, your project's own commands, such as its linter and tests. It's done when a second discern tidy --dry-run reports 0 files would change.

To find out whether a newer discern is out, ask your agent or run:

discern releases

discern releases points you to the release page, which shows what's changed and whether an upgrade is available. The desk, the interactive view that opens when you run discern in your main checkout, your original project folder, lists Check for updates… beside the Commands row it opens on, and under Ctrl+K. Your agent does only what you ask: a check, or a check and an install. discern status, discern doctor, and the deskDesk↗The interactive view that opens when you run discern in your main checkout. remind you to check every 14 days.

discern never downloads a new version or replaces itself, so you install the new program, and then your agent updates your project's setup to match.

Use the installerInstaller↗The script that downloads the discern program, checks it, and installs it on your machine. from Installation and setup, then open a new terminal and confirm which program runs:

command -v discern
discern --version

Restart your coding-agent sessions so they use the new version.

Say you've installed discern 1.0.1 on a project that 1.0.0 last set up. discern doctor and discern status now tell your agent:

This project was last upgraded with discern 1.0.0; this binary is 1.0.1. Preview the changes with `discern upgrade --dry-run`, then run `discern upgrade`.

Ask your agent:

"Update this project for the discern versiondiscern version↗The version of discern you're running, shown by discern --version. I just installed. Keep our instructions and skills, and bring the upgrade back with what passed."

The agent previews first, in a clean worktreeWorktree↗A separate copy of your project, on its own branch, where one task's work happens.:

discern upgrade --check
discern upgrade --dry-run

The agent runs discern upgrade, which changes only discern's own settings and files. If upgrade can't finish, its result says what's left and how to recover. Then the agent runs the gateGate↗The full set of checks your project requires before a change counts as finished. and brings the upgrade back for review, as in Finish and land a change. If your project runs discern in CI, raise the version CI installs in the same change, as Run the gate in CI explains.

After it lands, restart your coding-agent sessions. The upgrade is done when discern doctor passes, discern upgrade --check lists nothing, and a new session can reach discern.

Teammates get the upgrade when they pull it. A teammate still on 1.0.0 then sees:

This project was last upgraded with discern 1.0.1; this binary is 1.0.0. Check releases before changing discern-managed files: run `discern releases`. After installing a suitable update, restart your coding-agent sessions. Development builds may be ahead of the latest public release.

Until they upgrade, their discern still reads the project and runs tests, but it won't run the gate or change discern's files.

You can stop using discern and keep everything you wrote. Ask your agent to help you prepare:

"Help me remove discern from this repository. Find unfinished work that needs attention, and explain the removal preview and what will stay."

You run the removal yourself, in your main checkout, your original project folder, because discern uninstall isn't among the tools discern gives your agent.

Land the work you want to keep, and review anything you'll throw away. Uninstall refuses while any task worktree is still registered, even a finished one you kept:

refusing to uninstall while 1 linked worktree(s) are still active — land or remove them first, then uninstall from the main checkout.

It also refuses while discern still tracks a resource a worktree set up, such as a test database, because that record holds the command that removes it. discern worktree prune cleans these up.

discern uninstall --dry-run

The plan lists what discern removes:

• the files it generated, such as each tool's instruction file;
• its entries in files it shares with you, such as .gitignore;
• its own Git settings and the state it keeps inside .git.

It keeps discern.toml, your instructions, skills, scripts, map, and work ledger. It also keeps every Git reference, including recovery references that may be the only name left for some of your commits, and prints the commands to remove them later. Files and ownership lists every file and who owns it.

discern uninstall

In a terminal, uninstall asks you to confirm. Without that prompt, it changes nothing until you add --yes, so add that only after you've reviewed the preview. Then check git status and commit the removal as you usually would.

Uninstall leaves the discern program installed, because other projects may still use it. If none do, find it with which discern and delete that file.

Removal is done when the planned removals have happened, everything you wrote is still there, and no resource was left without its cleanup record. Worktrees and resources helps when something blocks uninstall.