Candor documentation

Quickstart

1. Install

$curl -fsSL https://candor.sh | bash

This installs the Candor CLI via npm, authenticates you via the browser, and installs the Candor skill for Claude Code.

2. Run a study

$claude "test the onboarding flow with 5 users"

Your agent reads your codebase for context, drafts a study script, shows you the cost estimate, and waits for your approval before recruiting.

3. Get results

$candor study study_a1b2c3

View prioritized findings (P0-P3) with key quotes and suggested fixes. Or ask your agent to open GitHub issues for the top findings.

How it works

When you ask your coding agent to run a user study, it uses the Candor CLI to create the study and recruit real participants from a research panel. Each participant joins a live session where they use your product while an AI voice moderator conducts the interview — asking questions, giving tasks, and adapting follow-ups in real time.

After all sessions complete, Candor synthesizes transcripts into prioritized findings with severity ratings, key quotes, and suggested actions. Your agent can then act on the results — opening issues, proposing fixes, or running follow-up studies.

candor init

Set up Candor: authenticate and configure Claude Code integration.

$candor init

This command:

• Opens your browser to authenticate with candor.sh
• Saves your API key to ~/.candor/config.json
• Installs the Candor skill to ~/.claude/skills/candor/

candor login

Re-authenticate with Candor. Use this if your API key has expired or you need to switch accounts.

$candor login

candor create-study

Create a new AI-moderated user study.

$candor create-study --url https://myapp.com --goal "test the onboarding flow"

Options

Response (JSON)

{
  "study": {
    "id": "study_a1b2c3",
    "name": "Onboarding flow test",
    "status": "draft",
    "targetProductUrl": "https://myapp.com",
    "targetParticipants": 5,
    "estimatedCostCents": 7250
  }
}

candor studies

List all studies in your organization and their current status.

$candor studies

Output

Your Studies

  Onboarding flow test [completed] id:study_a1b2c3
    https://myapp.com | 5 participants

  Pricing page clarity [recruiting] id:study_d4e5f6
    https://myapp.com/pricing | 3 participants

Studies are listed with their name, status, ID, target URL, and participant count. Status is one of: draft, recruiting, active, completed. Supports --json.

candor study

View results and findings for a specific study.

$candor study <study-id>

Arguments

candor status

Get current status of a study including participant progress.

$candor status <study-id>

Response (JSON)

{
  "study": {
    "id": "study_a1b2c3",
    "name": "Onboarding flow test",
    "status": "active",
    "targetParticipants": 5,
    "completedSessions": 3,
    "pendingSessions": 2
  }
}

candor findings

Get prioritized findings (P0–P3) for a study.

$candor findings <study-id>

Response (JSON)

{
  "findings": [
    {
      "priority": "P0",
      "title": "\"Add guests\" button hidden on mobile",
      "category": "usability",
      "description": "Users could not find the primary CTA on small screens",
      "timesMentioned": 3,
      "keyQuotes": ["I kept scrolling but couldn't find how to add people"],
      "suggestedAction": "Move CTA above the fold on mobile viewports"
    }
  ]
}

candor approve

Approve a study to begin recruiting real participants. This is the human-in-the-loop gate — studies do not recruit until explicitly approved.

$candor approve <study-id>

candor doctor

Run diagnostic checks on your Candor installation.

$candor doctor

Checks for:

• Candor CLI installed and up to date
• API key configured
• Claude Code detected
• Skill file installed

candor update

Update the Candor CLI to the latest version.

$candor update

Studies

A study is a research session targeting a specific product URL with a defined goal. When created, Candor auto-generates a study script — a structured set of sections, questions, and tasks for the AI moderator to follow during participant sessions.

Each study has a target number of participants, optional demographic filters, and a cost based on the number of sessions (~$14.50 per participant).

Study lifecycle

Every study moves through four states:

AI moderator

Each session is conducted by an AI voice agent that joins the participant in a live call. The moderator follows the study script but adapts follow-up questions based on participant responses. It can ask open-ended questions, assign tasks ("try signing up"), and probe on confusion or frustration it detects.

Sessions are capped at 35 minutes. The moderator records transcripts and audio, which are later synthesized into findings.

Findings

After all sessions complete, Candor analyzes the transcripts and produces prioritized findings:

Each finding includes the title, description, category, affected feature/page, number of times mentioned, key participant quotes, and a suggested action.

Pricing

Candor charges per participant session. The current rate is ~$14.50 per session, which covers participant recruitment, the AI-moderated interview, transcript generation, and findings synthesis.

A typical 5-participant study costs approximately $65–$75. Your agent will always show the cost estimate before you approve recruitment.