Skip to content
Briar
View on GitHub

CLI reference

briar extract

Mine live state from GitHub / Bitbucket / AWS / Jira / Linear / Sentry / meeting transcripts into a markdown knowledge blob written to local disk (or Postgres). The blob is named knowledge:<company> by default and becomes the source of truth other commands splice into agent prompts.

Synopsis

$ briar extract --company COMPANY [--include EXTRACTOR ...] [--storage {file,postgres}]
              [--blob-name NAME] [--root PATH] [--out-json PATH]
              [--merge-claude-md] [--claude-md-path PATH]
              [<provider flags>] [<per-extractor flags>]

Available extractors

Twenty-three scheduled extractors ship today. Each one is independent — if its required credentials are missing, it skips silently and the rest of the pipeline runs unchanged.

Context & activity

  • active-tickets — open tracker tickets per project (Jira / GitHub Issues / Bitbucket Issues / Linear).
  • active-work — open PRs + recent activity from the configured repo provider.
  • aws-infra — AWS / GCP / Azure inventory: compute, databases, queues, log groups.
  • code-hotspots — files churned most often in the last N days; high-risk surface area.
  • codebase-conventions — language / framework / test-runner / migration-tool detection.
  • github-deployments — recent deployment events from GitHub's deployments API.
  • meeting-digest — Fireflies transcript summaries with attendee filters.
  • pr-archaeology — merged PRs with titles, descriptions, review patterns.
  • reviewer-profile — who reviews what, how fast, what they typically catch.
  • ticket-archaeology — closed tickets with resolutions, useful for context on recurring bugs.

Code quality & engineering health

Thirteen extractors mine git history and the repo-host API for engineering-quality signals. All take --provider github|bitbucket and a per-extractor --<name>-repo owner/repo flag (repeatable). See agents/extract.md for the full per-extractor flag reference.

  • defect-hotspots — files most likely to break, scored by churn × bug-fixes × size.
  • pr-hygiene — PR size distribution, large-PR rate, rubber-stamp rate, time-to-first-review.
  • review-nits — phrases reviewers repeat across PRs; candidates to codify as lint rules.
  • revert-signals — reverts and emergency fixes; fragile areas the test/review net missed.
  • commit-message-quality — conventional-commits adherence and subject-line hygiene.
  • stale-prs — open PRs idle beyond a threshold; the review backlog.
  • ci-health — pass rate, flaky workflows, run-duration trend.
  • dependency-health — open dependency vulnerabilities by severity (Dependabot).
  • code-scanning — open static-analysis findings grouped by rule and file.
  • repo-governance — branch protection + presence of CODEOWNERS / pre-commit / linter config.
  • test-discipline — test-to-source file ratio and source files without an obvious test.
  • release-cadence — how often the repo ships: release frequency and recency.
  • todo-density — count of TODO / FIXME / HACK markers and the files carrying the most.

Cherry-pick with --include

Without --include, every extractor with valid credentials runs. Pass --include <name> (repeatable) to run only specific extractors.

Examples

Full extract for a company

$ briar extract --company acme

Writes knowledge:acme to ./knowledge/knowledge/acme.md. Runs every extractor whose credentials are configured.

Specific extractors with filters

$ briar extract --company acme \
    --include pr-archaeology \
    --include reviewer-profile \
    --pr-repo acme/widgets \
    --pr-repo acme/api \
    --pr-max 50 \
    --pr-authors-block dependabot \
    --pr-authors-block renovate

Write to Postgres

$ briar extract --company acme --storage postgres

Requires BRIAR_DATABASE_URL (or the per-company override). The blob name is unchanged — only the backend differs.

Custom blob name (archive snapshot)

$ briar extract --company acme \
    --blob-name knowledge:acme.archive-2026q1

Non-AWS cloud

$ briar extract --company acme \
    --include aws-infra \
    --cloud gcp \
    --aws-extract-profile my-gcp-project \
    --aws-extract-region us-central1

The flag names read AWS-flavoured because the AWS provider shipped first. For GCP --aws-extract-profile carries the project ID; for Azure it carries the subscription ID.

Code-quality signals

$ briar extract --company acme \
    --include defect-hotspots --risk-repo acme/widgets \
    --include pr-hygiene --prhygiene-repo acme/widgets \
    --include ci-health --cihealth-repo acme/widgets \
    --include review-nits --nits-repo acme/widgets

Each code-quality extractor takes its own --<name>-repo flag (repeatable). They read git history plus the repo-host API — no extra credentials beyond the provider token already in use.

Feed CLAUDE.md — read on demand

$ briar extract --company acme \
    --include defect-hotspots --risk-repo acme/widgets \
    --include ci-health --cihealth-repo acme/widgets \
    --merge-claude-md

Writes the full bundle to .briar/knowledge/acme.md and splices a short topic index into CLAUDE.md. Because CLAUDE.md auto-loads into every Claude Code session but the detail file does not, the agent reads the detail only when a task touches one of the listed topics — knowledge on demand, without a per-session context cost.

Non-destructive, re-runnable

The index lives inside a <!-- BEGIN briar-knowledge --> … <!-- END briar-knowledge --> block. Re-running replaces only briar's block and leaves any hand-written CLAUDE.md content untouched. The detail file is written locally even with --storage postgres, since the reference resolves from the project root.

Core flags

--company COMPANYrequired
Company name. Drives the markdown title, the default blob name, and the per-company env-var interpolation (GITHUB_{COMPANY}_TOKEN, etc.).
--include EXTRACTOR
active-ticketsactive-workaws-infraci-healthcode-hotspotscode-scanningcodebase-conventionscommit-message-qualitydefect-hotspotsdependency-healthgithub-deploymentsmeeting-digestpr-archaeologypr-hygienerelease-cadencerepo-governancerevert-signalsreview-nitsreviewer-profilestale-prstest-disciplineticket-archaeologytodo-density
Which extractor to run. Repeatable. Omit to run every extractor whose credentials are present.
--storage {file,postgres}default: file
filepostgres
Where to write the result. Postgres requires BRIAR_DATABASE_URL.
--blob-name NAMEdefault: knowledge:<company>
Storage blob name. Useful for snapshots — knowledge:acme.archive-2026q1 won't clobber knowledge:acme.
--root PATHdefault: ./knowledge
Local file root. Only used when --storage=file.
--out-json PATH
Parallel JSON output path. The markdown still lands in the configured store; JSON is a sidecar useful for piping into downstream tooling.
--merge-claude-md
Also merge a knowledge index into CLAUDE.md so Claude Code sessions can read the full detail on demand. Writes the bundle to .briar/knowledge/<company>.md and splices a short, marker-bounded topic index into CLAUDE.md — re-runs replace only briar's block. Off by default.
--claude-md-path PATHdefault: ./CLAUDE.md
Which CLAUDE.md to merge the index into. Only used with --merge-claude-md.

Provider flags

Pick which provider implementation the extractors talk to.

--provider {github,bitbucket}default: github
githubbitbucket
Repository provider used by active-work, pr-archaeology, reviewer-profile, code-hotspots, codebase-conventions, and all thirteen code-quality extractors.
--cloud {aws,gcp,azure}default: aws
awsgcpazure
Cloud provider used by aws-infra.
--tracker {jira,github-issues,bitbucket-issues,linear}default: jira
jiragithub-issuesbitbucket-issueslinear
Tracker provider used by active-tickets and ticket-archaeology.
--meeting {fireflies}default: fireflies
fireflies
Meeting provider used by meeting-digest.

PR-archaeology / active-work flags

--pr-repo owner/repo
Repository slug to mine. Repeatable.
--pr-max Ndefault: 100
Max merged PRs per repo.
--pr-authors-allow LOGIN
Only include PRs whose author is in this list. Repeatable.
--pr-authors-block LOGIN
Exclude PRs by author. Repeatable. Useful for bot exclusion (dependabot, renovate).
--pr-assignees-allow LOGIN
Only include PRs assigned to logins in this list. Repeatable.
--pr-assignees-block LOGIN
Exclude PRs by assignee. Repeatable.

AWS / cloud flags

--aws-extract-profile PROFILE
Local AWS profile name (falls back to the default boto3 credential chain). For GCP/Azure this carries the project ID / subscription ID.
--aws-extract-region REGIONdefault: us-east-1
AWS region to inspect. For GCP/Azure this is the matching region / location.
--aws-extract-service {ecs,lambda,logs,rds,sqs,tagging-inventory}
ecslambdalogsrdssqstagging-inventory
Which AWS services to include in the inventory. Repeatable. Default: all of them. The first five describe one service each; tagging-inventory walks the Resource Groups Tagging API to enumerate every tagged resource across all services.

Account-wide inventory, without prompt bloat

tagging-inventory keeps the knowledge blob small — only per-service counts go in the markdown body, while the full per-resource detail (ARN, type, region, tags) rides in the section's structured data. Persist it with the JSON sidecar (--out-json), or set knowledge.config.inventory: "true" in a runbook to write a byte-stable inventory:<company> companion blob that only changes when the estate drifts. Tagged resources only — untagged need AWS Config / Resource Explorer.

active-work flags

--active-repo owner/repo
Repository slug to scan for active work. Repeatable.
--active-authors-allow LOGIN
Only include items by author. Repeatable.
--active-authors-block LOGIN
Exclude items by author. Repeatable.
--active-assignees-allow LOGIN
Only include items by assignee. Repeatable.
--active-assignees-block LOGIN
Exclude items by assignee. Repeatable.

github-deployments + codebase-conventions

--deploy-repo owner/repo
Repository slug to scan for deployments. Repeatable.
--conventions-repo owner/repo
Repository slug to detect conventions for. Repeatable.

Ticket flags

--ticket-project PROJECT_KEY
Tracker project key to scan for active tickets. Repeatable.
--ticket-archaeology-project PROJECT_KEY
Tracker project key to mine for closed tickets. Repeatable.
--ticket-max Ndefault: 100
Max closed tickets per project.

reviewer-profile flags

--reviewer-repo owner/repo
Repository slug to profile reviewers for. Repeatable.
--reviewer-pr-sample Ndefault: 20
How many recent merged PRs to sample per repo.
--reviewer-top-n Ndefault: 5
How many top reviewers to profile per repo.

code-hotspots flags

--hotspots-repo owner/repo
Repository slug to analyse. Repeatable.
--hotspots-since-days Ndefault: 30
Commit lookback window in days.
--hotspots-max-commits Ndefault: 100
Max commits to inspect per repo.
--hotspots-top-n Ndefault: 10
How many hotspot files to surface per repo.

meeting-digest flags

--meeting-since-days Ndefault: 7
How many days back to scan.
--meeting-max Ndefault: 25
Cap on meetings included in the digest.
--meeting-attendee-allow EMAIL
Only include meetings with at least one of these attendee emails. Repeatable. Empty = no filter (every accessible meeting).

See also

  • briar runbook — declarative form of briar extract via a YAML schedule.
  • briar secrets doctor — audit which extractors have valid credentials for a given company.
  • Plugin registries — full list of providers, trackers, clouds, and AWS service gatherers.