Configuration

Configuration

Conscience works with zero configuration. Everything here is optional enrichment.

conscience.yaml

A project manifest that gives conscience human context it can't get from data. Place it in your project root (or wherever --project points).

Minimal example

project:
  name: "My Project"
  mission: "What this project is for"

Full example

project:
  name: "My Project"
  mission: "Help teams evaluate their AI-assisted work"
  beneficiaries:
    - name: "Engineering teams"
      description: "Teams using AI coding tools who want to reflect on impact"
    - name: "End users"
      description: "Better reflection leads to better products"
  cost_bearers:
    - name: "Engineering time"
      description: "Time spent on reflection and maintaining conscience.yaml"
  # Other checkouts that count as this project (git worktrees, sibling clones).
  # Absolute, ~/-relative, or relative to this file.
  worktrees:
    - "../my-project-feature-branch"

github:
  # Used when --repo is not given. Overrides the checkout's origin remote,
  # which is handy for forks where origin is yours and the project is upstream.
  repo: "your-org/my-project"

team:
  size: 5
  roles:
    senior: 2
    mid: 2
    junior: 1
  learning_goals:
    - "Learn Rust"
    - "Understand ethical AI evaluation"

monthly_review:
  last_updated: "2026-09-01"
  value_delivered: "Shipped v1 with core analysis features"
  revenue_impact: "No revenue yet — inception-phase project"
  growth_observations: "Team learning about ethical frameworks"
  ethical_notes: "We are using AI to build a tool that evaluates AI usage"
  ai_sentiment: "mostly_positive"

thresholds:
  contribution_concentration_warn: 0.80
  contribution_concentration_concern: 0.60
  ai_dependency_info: 6.0
  ai_dependency_concern: 12.0
  tokens_per_file_warn: 100000
  tokens_per_turn_warn: 20000
  max_session_hours: 12.0
  solo_project: false

  attention:
    idle_minutes: 15
    engagement_floor_minutes: 2
    flow_gap_minutes: 10
    flow_min_minutes: 20
    project_aliases:
      "/private/tmp/worktrees/*": my-project

  energy:
    grid_carbon_intensity: 0.42
    overrides:
      "my-custom-model":
        wh_per_1k_input: 0.5
        wh_per_1k_output: 2.0

What each section does

project — Names and describes the project. beneficiaries and cost_bearers enrich the Equity of Benefit reflection question. mission appears in the revenue reflection. worktrees lists other checkouts whose AI sessions belong to this project, so a feature-branch worktree doesn't look like a separate project.

github — repo names the GitHub repository (owner/repo) for every command that fetches commits and PRs, when --repo is not given. It takes precedence over the checkout's origin remote, which matters for forks: origin is usually your fork and the project lives upstream. Without it, the origin remote is used when it points at GitHub.

team — Team composition. learning_goals appear in the Developer Growth reflection. If roles.junior > 0 and learning_goals is empty, a signal fires.

monthly_review — Human-written assessment, updated periodically. If last_updated is more than 30 days old, a "stale review" signal fires. ai_sentiment accepts: mostly_positive, mixed, mostly_negative, unknown.

thresholds — Tune when signals fire. All have defaults; only override what you want to change.

Threshold	Default	What it controls
contribution_concentration_warn	0.80	Warn when top contributors account for this % of commits
ai_dependency_concern	12.0	AI:Human ratio that triggers a Concern signal
ai_dependency_info	6.0	AI:Human ratio that triggers an Info signal
tokens_per_file_warn	100,000	Tokens per file before "high token-to-file ratio" fires
max_session_hours	12.0	Session length before "extremely long session" fires
solo_project	false	Set true to suppress contribution-concentration signals for solo projects

thresholds.attention — See Understanding Your Attention Patterns.

thresholds.energy — See Measuring Energy Cost.

GitHub Authentication

Conscience tries three methods in order:

1. gh CLI — If GitHub CLI is installed and authenticated (gh auth login), it just works. Zero config.
2. Environment variable — CONSCIENCE_GITHUB_TOKEN set to a personal access token.
3. Config file — ~/.conscience/config.toml:

[github]
token = "ghp_your_token_here"

Run conscience setup to see which method is active.

Dashboard

Configure the dashboard endpoint for conscience push:

Environment variable:

export CONSCIENCE_DASHBOARD_URL=https://your-dashboard.example.com

Config file (~/.conscience/config.toml):

[dashboard]
endpoint = "https://your-dashboard.example.com"
api_key = "your-api-key"

CLI flag (overrides both):

conscience push --endpoint https://your-dashboard.example.com

See Tracking Trends with a Dashboard.

AI Tool Support

Tool	Status	Data Source
Claude Code	Implemented	~/.claude/projects/ session logs
GitHub Copilot	Planned	—
Cursor	Planned	—
OpenAI Codex	Planned	—
Windsurf	Planned	—
OpenClaw	Planned	—
NanoClaw	Planned	—

Upgrading: AI:Human ratio threshold change

As of v0.2.0, tool-result messages are no longer counted as human turns. AI:Human ratios are substantially higher than before. The defaults were recalibrated to 6.0/12.0. If you have custom ratio thresholds in conscience.yaml, re-tune them.