live-comments

Comments tracked to their source, so your agents don't make up the rules.

Every business rule in your code cites the ticket, doc or file it came from, and stays in sync
as those sources are edited, as teams change, and as the code changes in review.
Every rule nobody has decided yet is an open question that stays open until someone with authority answers it.

Quick start · What it keeps in sync · Spec · Agent skill · Contributing

/** @source linear:ENG-142 "Only the best single discount applies per order" by pricing */
export function applyDiscounts(codes: Code[]): Price { … }

/** @open "Do discount codes stack with gift cards?" by pricing in linear:ENG-188 */
export function applyGiftCard(card: GiftCard, total: Price): Price { … }

live-comments check confirms the quote is still in ENG-142, that the person who wrote it is on the pricing team, and that the gift-card rule is still waiting on an answer. When someone on the pricing team answers in ENG-188, sync shows you their words, and the @open becomes a @source. If ENG-142 is later edited, or its author leaves the pricing team, the next sync tells you which rules that touches.

Why

Coding agents fill gaps. When a ticket doesn't say whether discount codes stack, an agent picks an answer, writes plausible code, and the tests pass. Nobody decided that rule. It just shipped.

Comments don't help, because nothing checks them. They go stale the day the ticket changes, and they can't say "this hasn't been decided."

Live comments fix both:

• Bound to the source. A @source cites a ref, optionally a verbatim quote, optionally who must have written it. The checker verifies all three, with no model in the loop.
• Open questions are explicit. An @open is a typed hole for a product decision: it records that a rule is undecided, who should decide it, and where the answer should come from. Agents are told never to fill it themselves.
• Authority comes from people. Who counts as pricing is defined once, in a governed AUTHORITY file that code can't change. Agents and bots never hold authority.

What that looks like after someone edits ENG-142, an engineer's comment gets quoted as a decision, and the pricing lead replies on the open question:

$ npx live-comments check
src/checkout/discounts.ts:12  LC002 error  quote not found in linear:ENG-142: "Only the best single discount applies per order"
src/checkout/refunds.ts:7  LC009 error  linear:usr_31a in linear:ENG-150 does not satisfy 'by pricing'
src/checkout/giftcards.ts:4  LC019 info  possible answer in linear:ENG-188 by linear:usr_8f2: "No: gift cards apply after discounts."
src/checkout/giftcards.ts:4  LC100 info  open: "Do gift cards stack with discounts?" — to be answered by pricing in linear:ENG-188

2 error(s), 0 warning(s), 2 note(s)

The @open tag

Most tools can only describe decisions that were made. @open describes one that wasn't:

/** @open checkout.gift-cards "Do gift cards stack with discounts?" by pricing in linear:ENG-188 options "yes" | "no, applied after" */

It is a typed hole for a product decision: it records that the rule is undecided, who may decide it, and where the answer should be written. The common cases:

• Someone on the pricing team answers in ENG-188. sync quotes their reply as a possible answer, and you (or your agent) flip the @open to a @source citing it.
• Anyone else answers, including a coding agent. It isn't treated as an answer, and a @source quoting it is rejected.
• The answer is later edited, or its author leaves the team. The next sync flags the rule as stale or no longer authorized.

What it keeps in sync

A comment's status is never stored. It is recomputed from the code, the lockfile, AUTHORITY and the config, so when any of them changes, sync and check --base report exactly which rules moved:

Before you start

Live comments read your tickets and docs through an integration platform, so you need an account on Composio or Nango to cite anything outside the repository. Live Comments never stores your tool credentials; the platform handles sign-in and token refresh, and Live Comments only asks it for the documents you cite.

You can mix them: each tool picks its platform in live-comments.config.json. For Jira, connect finds your site through the connection; pass --base-url https://<site>.atlassian.net only for API-token connections. With a hosted platform, the text of the tickets and docs you cite passes through that provider, so pick the one your security review allows.

Files in your own repository need neither: @source file:docs/pricing.md works out of the box, attributed with git blame.

Quick start

Tell your coding agent:

Set up live-comments from github.com/BicameralAI/live-comments

Or do it yourself:

npx live-comments init                  # config, AUTHORITY, the agent skill, MCP setup
npx live-comments connect github        # sign in through Composio (or --via nango)
npx live-comments sync                  # read every cited source into the lockfile
npx live-comments check                 # verify; exits non-zero on errors

init installs the agent skill in .agents/skills/ and in each agent folder your project already has (Claude Code, Cursor, Copilot), and registers the live-comments MCP server. Agents then read sources through read_source, which is the exact text the checker verifies, so their quotes always match.

In CI:

- name: Check live comments
  run: npx live-comments check --base origin/${{ github.base_ref || 'main' }}

With --base, the check also reports every authority change in the pull request, such as by pricing → by eng, so reviewers see who is deciding what even in a large diff.

AUTHORITY

jdoe          = github:jdoe | linear:usr_8f2 | email:jdoe@acme.com
agent claude  = github:acme-claude[bot]
pricing       = jdoe | members(linear:team/PRICING)
pricing-desk  = linear:team/PRICING | notion:space/Pricing
pricing-call  = pricing in pricing-desk
launch-call   = pricing-call & legal

A vocabulary of names, not a map of owners: which name applies is written on each rule with by. | means either, & means both, in restricts where the words were written. See SPEC.md §7.

Commands

Packages

Live comments and Bicameral

Live comments share Bicameral's rule that no product decision is made without human supervision, and cover a narrower job. Live Comments binds each comment to a source and checks who wrote the words it rests on. It does not judge whether that source is still the team's current, ratified decision. Keeping decisions current, superseded or signed off is what Bicameral does. The two fit together: Bicameral keeps the decision ledger, and live comments keep the code pointing at it.

Status

Early preview. What works and is tested:

• Annotation parsing, authority expressions, normalization and the comment lifecycle, covered by unit, property-based and model-based (state machine) tests
• The CLI end to end in a real git repository, including the MCP server
• All six sources read live through Composio: GitHub end to end against a public repository (open question, answer, flip), and Linear, Notion, Jira, Google Docs and Slack read and attributed against real workspaces
• Every extractor also against recorded API responses, including error mapping and partial access (a Notion page without comment access, a Google Doc without Drive)

Not done yet: live tests of the Nango transport and the Composio SDK path; languages other than TypeScript. The spec lists the open design questions.

Contributing

Everyone is welcome. Open an issue with a use case, a missing extractor or a disagreement with the spec. CONTRIBUTING.md covers setup, how the pieces fit, and the test suite.

License

MIT