Command Reference

Command Reference

Six commands. examine and reflect are things you do to one project; report holds diagnostic topics; retro and push work from records earlier runs saved.

How every command behaves

• The current directory is the project. --project <path> points elsewhere. Worktrees and sibling clones can be declared as the same project in conscience.yaml (see Configuration).
• The GitHub repository follows the project. --repo if given, else github.repo in conscience.yaml, else the checkout's origin remote when it is on GitHub. A detected repository is only fetched when GitHub auth is available; otherwise the coverage line says which repository was found and how to log in, and nothing fails. --no-github opts out.
• --all is explicit. Nothing scans every project on the machine unless you ask.
• One interval per run. --days N (or --since 4h for tokens) applies to GitHub and to AI sessions alike. Sessions with no timestamp are counted and reported, never silently included or dropped.
• --json is the machine format on every command that has one.
• Every run prints what it covered on stderr: the resolved project, the interval, how many sessions and PRs were in range, and which sources were collected, unavailable, failed, or skipped.

---

conscience setup

Check which integrations are configured and show directions for anything missing.

conscience setup

Checks GitHub auth, conscience.yaml, Claude Code logs, the dashboard endpoint, and the GitHub Actions workflow. See Getting Started.

---

conscience examine

Ethical analysis: what was analyzed, what deserves attention, what is worth discussing.

conscience examine [--repo <owner/repo> | --no-github] [--project <path>] [--days 30] [--json] [--full]
conscience examine --pr <url | owner/repo#N> [--project <path>] [--json] [--comment | --markdown]
conscience examine --all [--days 30] [--json]
conscience examine --all --markdown [--output <file>] [--days 7]

Flag	Meaning
--repo	Include commits and PRs from this GitHub repository. Default: github.repo in conscience.yaml, else the checkout's origin remote
--no-github	Skip GitHub even if a repository can be detected
--project	Project directory (default: current directory)
--days	Interval ending now (default 30)
--pr	Analyze one pull request over its own lifetime, from opened to merged (or closed, or now)
--comment	With --pr: post the analysis as a comment on the pull request. Built from the sanitized export, so no paths, commands, or names. A re-run edits conscience's earlier comment instead of adding another. Project-configuration signals are left out
--markdown	With --pr: print the comment body instead of posting. With --all: the Markdown digest
--all	Every project with Claude Code data on this machine, with cross-project outliers
--markdown	With --all: a Markdown digest for retrospectives and weekly summaries
--output	With --markdown: write to a file instead of stdout
--full	Every signal, the scorecard table, and all seven reflection questions
--json	The full snapshot as JSON

Default output is deliberately short: the snapshot header, then concern and warning signals only, then one reflection question for the principle with the most serious signal. --full restores the complete report. When nothing is flagged the output says no concerns or warnings detected in the available data, which is not the same claim as healthy.

Every examine writes a snapshot to .conscience/snapshots/<id>.json (gitignored). A snapshot records the project, the interval, per-source coverage, metrics with units and uncertainty, the analyzer version and a fingerprint of the thresholds used, and the analysis itself. push uploads snapshots; history compares them. Two snapshots whose intervals overlap are separate assessments and are never summed. --all does not write snapshots, since that would write into other repositories.

See Getting Started, Evaluating a Pull Request.

---

conscience report <topic>

Diagnostic views of one data source. All default to the current project except attention; --all widens to every project.

conscience report github     [--repo <owner/repo>] [--project <path>] [--days 30]
conscience report ai         [--tool claude-code] [--project <path> | --all]
conscience report energy     [--project <path> | --all] [--days 30] [--json]
conscience report tokens     [--since 4h] [--project <path> | --all] [--json]
conscience report authorship [--repo <owner/repo>] [--project <path>] [--days 30] [--json]
conscience report attention  [--days 7] [--project <path>] [--json] [--html <file>]
conscience report history    [--project <path>] [--days 90] [--json]

Topic	What it shows
github	Commits, PRs, contributors, and review patterns for a repository
ai	Sessions, tokens, tools called, files touched, all time. --tool filters to one assistant; Claude Code and Codex are implemented
energy	Estimated Wh, CO2, and water per model, with uncertainty ranges. See Measuring Energy Cost
tokens	Where the token budget went in a recent window. --since takes 90m, 4h, 2d, 1w; a bare number is hours
authorship	Per-contributor correlation between commit times and AI sessions. A prompt for investigation, not a finding about who wrote what
attention	Active time, context switches, flow, and orchestration across projects. Defaults to every project because switching between them is the subject. See Understanding Your Attention Patterns
history	Change over time from the project's saved snapshots. Groups snapshots by the interval they cover and compares each group's latest two: metric deltas (estimates marked ~), signals that appeared and resolved, and whether thresholds or the analyzer version changed in between. Pull request snapshots are listed but never compared. Ends with readings for the questions it exists to answer: is the AI:human ratio rising, are review comments per PR falling, is energy per output token growing, are security signals trending down

---

conscience reflect

Reflection questions for a team retrospective, grounded in the seven principles and enriched with whatever data is available.

conscience reflect [--repo <owner/repo> | --no-github] [--project <path>] [--days 30] [-i] [--save [<path>]] [--json]

Flag	Meaning
-i, --interactive	Answer each question at a prompt. Multi-line answers end with a blank line; Enter skips; Ctrl-D skips the rest
--save	Persist the answered session to .conscience/reflections/<session-id>.json, or to the given path
--json	The questions (or, with -i, the answered session) as JSON

Works with no data at all. reflect does not write a snapshot; it is a conversation aid, not an assessment on the record. See Running a Team Retrospective.

---

conscience retro

Aggregate saved reflection sessions into a team view: every answer to each question, grouped by principle, with who answered and who skipped.

conscience retro [--dir <path>] [--days 30] [--json]

Reads .conscience/reflections/ in the current directory by default. --days selects sessions by their timestamp; sessions outside the window or with an unreadable timestamp are counted and reported. See Running a Team Retrospective.

---

conscience push

Send a saved snapshot to a dashboard server.

conscience push [<snapshot>] [--project <path>] [--endpoint <url>] [--show]

Argument	Meaning
<snapshot>	A snapshot id, a unique prefix of one, or a file path. Default: the latest snapshot for the project
--endpoint	Dashboard URL; overrides CONSCIENCE_DASHBOARD_URL and ~/.conscience/config.toml
--show	Print exactly the JSON that would be sent, and send nothing

push never re-runs analysis. Run examine, look at the result, then push that exact snapshot. Only an allowlisted export leaves the machine: the analysis, metrics, coverage, and analyzer info go; file paths, shell commands, PR titles inside signals, contributor names inside signals, session ids, the project's local path, and the text of collection errors do not. The export records what was replaced or removed. See Tracking Trends with a Dashboard.

---

Older spellings

Since 0.6.0 these still work but are hidden from --help and print a note pointing at the new form. They will be removed in a later release.

Old	New
conscience evaluate --pr X	conscience examine --pr X
conscience examine-all	conscience examine --all
conscience digest	conscience examine --all --markdown
conscience authorship	conscience report authorship
conscience attention	conscience report attention
conscience retro-tokens --hours N	conscience report tokens --since Nh
conscience push --repo X --days N	conscience examine --repo X --days N, then conscience push
conscience ingest github / ingest claude-code	Still available as a raw JSON dump for debugging, hidden from help