Get started

Core concepts.

Briar has five primitives. Once you understand how they compose, every command makes sense. Read once, refer back when you hit something that confuses you.

1. Knowledge files

A knowledge file is a markdown blob with a stable name. The default file backend writes them to ./knowledge/<category>/<name>.md; the postgres backend writes the same blobs to a database table. The shape is identical either way.

Two categories ship by default:

knowledge:<company> — long-lived, cold-rebuilt periodically by briar extract. Holds active tickets, PR archaeology, AWS infra inventory, codebase conventions, meeting digests, and 5 more sections.
plan:<name> — the body of an implementation plan, with one section per card. Cards carry status (pending / in_progress / done / blocked) and per-card writeback notes.
knowledge:<company>.<plan> — plan-scoped knowledge shard. Seeded at plan-build time, then appended to after every successful card by the writer step of briar plan run.

$ briar context list
$ briar context get knowledge:acme
$ briar context categories       # → ["knowledge", "plan"]

Why markdown?

Markdown is the universal LLM context format: every model provider reads it natively, every diff tool renders it, every editor highlights it. The structured-ness comes from section headings, not a custom schema.

2. Runbooks

A runbook is a YAML file that declares one or more companies, which extractors run on which schedule, where credentials come from, and which outbound message channels are wired up. It is the durable, version-controllable equivalent of a long briar extract command line.

version: 1
companies:
  acme:
    knowledge:
      store: file
      name: knowledge:acme
    extract:
      - name: pr-archaeology
        args:
          pr_repo: [acme/widgets]
      - name: active-tickets
        args:
          tracker: jira
          ticket_project: KAN
    schedules:
      - task: extractors
        every: "day at 07:30"
        extract:
          - name: pr-archaeology
          - name: meeting-digest

Three commands consume runbooks: briar runbook extract (single shot), briar runbook sweep (everything in a directory), and briar runbook serve (long-running in-process scheduler).

Full schema lives on the runbook YAML page.

3. Plans

A plan is an ordered list of cards (one per ticket on a board) annotated with scope, out-of-scope, risks, and inferred dependencies. Cards carry a status field; the LLM-driven selector picks the next pending card on every iteration of briar plan run.

$ briar plan build jira:KAN --name q3 --company acme --llm anthropic
$ briar plan status q3 --company acme
$ briar plan next   q3 --company acme --llm anthropic   # → "pick KAN-1"
$ briar plan run    q3 --company acme --llm anthropic --owner acme --repo widgets

The selector is LLM-driven, not a topological-sort over a dep-graph. It reads the journal (what was learned last time), the plan-scoped knowledge file, and the cards themselves, then picks the highest-leverage next card.

4. Agents

An agent is an LLM-driven tool-use loop. It reads context, decides on a tool call (bash / read_file / write_file / edit_file / send_message), executes, observes, and iterates. Two operations ship today:

briar agent implement — the engineer archetype. Picks a ticket, writes the code, opens a PR.
briar agent prfix — the pr-fixer archetype. Reads the open review comments on a PR, applies the fixes, replies inline.

Three more archetypes ship via briar scaffold (the triager, the pr-ci-fixer, the pr-conflict-resolver) but those are designed to run on a downstream orchestrator, not from the local CLI.

Agents read knowledge files

Before the LLM tool-use loop starts, the agent splices the per-company knowledge file (and the plan-scoped shard, when running inside plan run) into the prompt. Three JIT extractors — ticket-context, pr-review-context, meeting-context — run at agent-invocation time to add live, task-specific context on top.

5. The decision journal

Every command writes a structured-event session to ./journal/. Events include extractor timings, LLM stop reasons, selector decisions, agent tool calls, and PR URLs. The journal is what the selector reads to decide what to do next, and what you read to debug what happened.

$ briar journal list --command plan.run. --limit 5
$ briar journal show <session-id>
$ briar journal export <session-id> /tmp/last-run.json

How they compose

The five primitives chain together end-to-end:

A runbook tells extractors what to mine.
Extractors write knowledge files.
A plan is built from a board, seeded with the company knowledge file.
The selector picks a card from the plan; the agent implements it. Both read the knowledge file.
Every step writes to the journal. The next selector turn reads that journal.

The shortest mental model

Briar is a CLI that reads knowledge, picks work, writes code, and records what it learned — then does it again. Everything else is plumbing around that loop.