microsoft/clarity-agent

microsoft/clarity-agent

Description: Distill intent. Surface failure modes. Keep the plan current.

Language: Python

License: MIT

Stars: 227

Forks: 24

Open issues: 13

Created: 2026-04-29T21:37:41Z

Pushed: 2026-06-10T18:09:21Z

Default branch: main

Fork: no

Archived: no

README:

Clarity Agent

An AI thinking partner that pushes back.

Most AI tools help you execute faster. Clarity helps you figure out whether you're building the right thing in the first place by asking the questions that experienced architects, product managers, and safety engineers would ask. The answers are written down as human-readable documents you can review, share with your team, or export as Word docs for stakeholders; they also are available to agents so the work you do with Clarity outlasts any single conversation.

You: I want to build a real-time collaboration feature for our doc editor.

Clarity: Before we design that — what happens when two people edit the same
paragraph at the same time? Do you need true real-time (cursors, presence),
or is "no one loses work" the actual requirement? Those lead to very
different architectures.

Clarity runs as a desktop app, a web UI, or embedded in your coding agent. It produces a .clarity-protocol/ directory in your repo which contains human-readable markdown files capturing your problem, solution, failure analysis, and decisions. The clarity protocol stays current as your project evolves and is managed like source code.

Read more about the philosophy behind clarity agent in this blog post.

You can also join the Clarity Agent Discord to talk with the team, share feedback, and connect with the community.

Getting Started

Install

Download the desktop app (no terminal required):

Download the latest .dmg (macOS) or .exe installer (Windows) from the GitHub Releases page and install it directly. No prerequisites.

Or install via script (adds the clarity CLI and embeds Clarity into git repos):

*macOS / Linux:*

curl -fsSL https://raw.githubusercontent.com/microsoft/clarity-agent/main/scripts/install.sh | bash

*Windows (PowerShell):*

irm https://raw.githubusercontent.com/microsoft/clarity-agent/main/scripts/install.ps1 | iex

The installer downloads everything it needs — no prerequisites beyond git.

Or clone and install manually:

git clone https://github.com/microsoft/clarity-agent.git
cd clarity-agent
bash scripts/install.sh # macOS / Linux
.\scripts\install.ps1 # Windows

Launch and connect an LLM

macOS: Open Clarity.app from ~/Applications.

Windows: Run the installed app from the Start Menu, or run clarity from your terminal if you used the script installer.

Linux: Run clarity from your terminal.

On first launch, the setup wizard walks you through connecting an LLM provider.

Supported providers:

| Provider | Authentication options | | --- | --- | | Anthropic (Claude) | Claude Code login (claude login) · API key from console.anthropic.com | | OpenAI (GPT) | API key from platform.openai.com | | Azure AI | Microsoft sign-in · Azure CLI (az login) · API key | | GitHub Copilot | GitHub CLI (gh auth login) · personal access token | | Google Gemini | API key from Google AI Studio |

Clarity works best with frontier models — structured thinking is where model quality matters most. The setup wizard tests your credentials before saving them. Run clarity doctor at any time to re-check the configuration.

Start a session

The app opens the project picker. Create a new project or open an existing folder. Clarity will ask what you're working on and guide you through structured thinking about your problem, solution, and failure modes. Everything is saved to a .clarity-protocol/ directory — no codebase required.

Use it

For any kind of project — Open the app, create a project, and start talking. Clarity will ask what you're working on and guide you from there. No codebase required.

For a coding project — embed Clarity into your repo so your coding agent picks it up:

clarity embed /path/to/your-project

This adds an AGENTS.md snippet and a .clarity-protocol/ directory. These are plain files managed just like any other file in your repo — committed, reviewed in PRs, and diffed. From then on, your coding agent (Claude Code, Cursor, etc.) follows the process guides as part of its normal workflow.

What It Does

Clarity guides you through structured conversations, writing the results to the clarity protocol as it goes:

Problem clarification — "What problem are you solving? Who are the stakeholders? What does success look like?" Pushes you past vague intentions into testable criteria.

Solution exploration — "Given that problem, how might we solve it?" Explores approaches, surfaces tradeoffs, and checks that the solution actually addresses the problem.

Failure analysis — Multiple AI "thinkers" independently examine your system from different angles (security, human factors, adversarial, operational), then you work through the results together: grouping related failures, tracing causal chains, building management plans.

Decision tracking — Important choices get captured with criteria, options, and rationale. When upstream documents change, the agent knows which decisions might need revisiting.

Staleness tracking — Documents form a dependency graph. When your problem statement changes, Clarity knows your solution description might be stale and nudges you to revisit it.

What Comes Out

A .clarity-protocol/ directory:

.clarity-protocol/
├── summary.md # Brief summary of what this project is
├── notes.md # Principles and cross-cutting observations
├── observations.md # Patterns and coverage notes from analysis
├── goal/
│ ├── problem.md # What you're trying to achieve and why
│ ├── stakeholders.md # Who cares about the outcome
│ ├── requirements.md # Criteria any solution must satisfy
│ ├── open-questions.md # Unknowns that could change the approach
│ └── resolved-questions.md # Questions answered, with findings
├── solution/
│ ├── solution.md # What…