Command Reference

Command Reference

Eight commands. examine and reflect are things you do to one project; report holds diagnostic topics; retro and push work from records earlier runs saved; prune and du clean up after automation and after conscience itself.

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, and only activity inside the window counts: a session that straddles the window contributes its in-window tokens, turns, and commands, not its lifetime totals. Sessions with no timestamp are counted and reported, never silently included or dropped.
• Every AI tool with data is read. Claude Code and Codex sessions are merged under the same scope and interval; the coverage line shows one entry per tool.
• --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 the window of its work: from its earliest commit (or its opening, if earlier) to merged, closed, or now. Only AI activity inside that window counts
--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
--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]
conscience report automation [--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, per tool. --tool filters to one assistant; Claude Code and Codex are implemented, and every other command merges both
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
automation	Work that runs without a person present: cron and launchd entries that invoke Claude, Claude Code daemon jobs, and program-launched session signatures (same directory and prompt). Each with cadence, runs, failures, last success, tokens and energy, and observations such as "has never succeeded (18 runs)" or "blocked awaiting input for 46 days". Runs attach to a cron entry when their prompt appears in the command or the script it runs. Defaults to the whole machine; --project narrows the sessions

---

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.

---

conscience prune <id>

Remove the launcher behind an entry from report automation. Never touches session logs.

conscience prune <id> [--dry-run] [--yes]

Source	What prune does
cron line	Removes that exact line from your crontab; the previous crontab is saved under ~/.claude/pruned/ first
launchd agent	Unloads it and moves the plist under ~/.claude/pruned/
daemon job	Moves the job directory under ~/.claude/pruned/
program-launched runs with no launcher found	Nothing to remove; it says where to look

Shows the plan and asks before changing anything; --dry-run only shows it; --yes skips the prompt. Ids come from report automation and are stable across runs.

---

conscience du

What conscience takes up on disk, in two sections kept apart: what it wrote and may tidy (snapshots, saved reflections, its config, the backups prune keeps), and the AI tool logs it only reads and never deletes. Ends with the ratio between the two and, per project, the snapshot rate over the last 30 days and what that is per year.

conscience du [--project <path> | --all] [--json]
conscience du --tidy [--keep-days 90] [--dry-run] [--yes]

--tidy removes snapshots older than --keep-days while always keeping the two most recent of each interval length, and of PR snapshots, which is exactly what report history compares. Reflections are people's answers and stay; logs are off limits. Same shape as prune: show the plan, ask, --dry-run only shows.

---

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