Getting Started

Getting Started

This guide takes you from install to your first ethical analysis in about five minutes.

1. Install

Pick whichever method works for your setup:

# macOS / Linux
brew tap subversivesoftwareorg/tap
brew install conscience

# Any platform with Rust
cargo install conscience

# Or download a binary from:
# https://github.com/subversivesoftwareorg/conscience/releases

2. Check your setup

conscience setup

This shows a green ✓ or red ✗ for each integration, with directions to fix anything that's missing. The two most useful integrations are:

• GitHub authentication — needed for examine --repo, examine --pr, report github, and report authorship. Easiest: install GitHub CLI and run gh auth login.
• Claude Code logs — appear automatically at ~/.claude/projects/ after your first Claude Code session. Codex sessions under ~/.codex/sessions/ are read too, when present. Needed for examine, reflect, and the ai, energy, tokens, and attention reports.

Everything else (conscience.yaml, dashboard, GitHub Actions) is optional and can be added later.

3. Run your first analysis

From inside a checkout of a project you work on with AI tools:

cd ~/code/your-project
conscience examine

The current directory is the project, and its origin remote is the GitHub repository, so no flags are needed. The first lines of output say what was detected. To point at a different repository or directory:

conscience examine --repo your-org/your-repo --project ~/code/your-project --days 30

The output answers three things:

1. What was analyzed — the project, the interval, and which sources were collected (or weren't, and why)
2. What deserves attention — the concern and warning signals found in your data (contribution concentration, review gaps, AI dependency, token consumption, security concerns)
3. What is worth discussing — one reflection question for the principle with the most serious signal

Add --full to see every signal including the healthy ones, the scorecard mapping signals to the seven ethical principles, and all seven reflection questions.

Each run also saves a snapshot to .conscience/snapshots/ (gitignored). That's the record push uploads later, so what reaches a dashboard is exactly what you looked at.

If the checkout has a GitHub remote but you haven't logged in yet, GitHub is skipped and the coverage line tells you which repository it found and to run gh auth login. To leave GitHub out on purpose:

conscience examine --no-github

If you only have a GitHub repo (no local AI logs, no checkout):

conscience examine --repo your-org/your-repo --days 30

4. Try a retrospective

conscience reflect --interactive --project .

This walks through each reflection question one at a time. Type your answer (multi-line; blank line finishes), or press Enter to skip. At the end you get a session summary. Add --save to keep it:

conscience reflect -i --save

Sessions land in .conscience/reflections/, one file each. Once a few people have saved theirs, conscience retro shows every answer to each question side by side.

5. Enrich with conscience.yaml (optional)

Create a conscience.yaml in your project root to give conscience human context it can't get from data:

project:
  name: "My Project"
  mission: "What this project is for"
  beneficiaries:
    - name: "Who benefits"
      description: "How"

team:
  size: 3
  learning_goals:
    - "What the team is trying to learn"

This enriches reflection questions with your stated mission and beneficiaries, and enables signals that check whether your conscience.yaml is being maintained. See Configuration for all options.

What's next?

• Running a Team Retrospective — structured ethical reflection with your team
• Evaluating a Pull Request — check a single PR before merge
• Understanding Your Attention Patterns — see how you spend time across projects
• Command Reference — every command, every flag