# Braid: Decision Intelligence Layer for AI Coding Agents

## Code is cheap. Show me the decisions.

Your agents make dozens of choices in every change. Braid records each one as a decision you can read, question and trace, from review to production.

- [Install Braid](https://docs.braidkit.io/quickstart/#1-install-braid)
- [Setup guide for your agent](https://docs.braidkit.io/quickstart.agent.md)

### One decision, as the Review UI shows it

An illustrative braid, "Add cart totals". Decision D1 of 3, written by Claude Opus 5.5.

**D1: Store prices as whole cents**

Question: How should the cart store prices?

- Chosen approach: **Whole cents as integers.** $4.99 is stored as 499, so every total is exact.
- Other approach considered: **Dollars as decimal numbers.** Why not: 0.1 + 0.2 gives 0.30000000000000004, so totals drift by a cent.
- Other approach considered: **Text, like "4.99".** Why not: every sum must convert the text first.

The code it shaped, `cart/cart.go`, lines 10, 14 and 17:

```go
type Item struct {
    Name       string
    PriceCents int64 // $4.99 is 499
    Qty        int64
}

func Total(items []Item) int64 {
    var total int64
    for _, it := range items {
        total += it.PriceCents * it.Qty
    }
    return total
}
```

How the agent got here:

1. 10:42:08, Asked (prompt): "Add a cart that shows the order total."
2. 10:42:15, Looked at (2 tool calls): read `cart/cart.go` and `db/schema.sql`.
3. 10:42:31, Weighed (decision marker):
   - Chosen: whole cents as integers. In the agent's words, entry #4: "a float cannot hold 0.10 exactly, so store whole cents and every sum stays exact". What followed: wrote `cart/cart.go`, ran the cart tests.
   - Set aside: dollars as decimal numbers, because 0.1 + 0.2 gives 0.30000000000000004.
   - Set aside: text, like "4.99", because every sum must convert the text first.

## Nobody reads code anymore.

Not because we stopped caring. Agents write code faster than anyone can read it. Braid keeps the goal and the decisions with the change, so the next reader starts from the reasons, not a bare diff.

Understanding of a change over its life: without Braid, it rises while the agent works, drops at the pull request ("starts over from the diff") and again at the merge, and is near zero at the next incident ("why is this here?", "starts over from git blame"). With Braid, each trace step, each decision and the intent are captured as it rises, and carried to every reader through every handover.

- The developer. **Own what you ship**: Know what you're merging, and see the evidence for it.
- The reviewer. **Pass on the context**: Your reviewer reads the reasons first, then the diff.
- The organisation. **Pick up where you left off**: Months later, the why is still there, for you or a teammate.

## A decision keeps working after the review.

What decisions do for you. Each decision stays linked to the code it shaped. It is there for the next reader, the next merge and the next agent.

- **Understand any change**: See what your agent chose, what it set aside, and why. A long diff becomes a short list of decisions.
- **Review only what matters**: Each decision shows the tests that cover it. You and your team spend review time on the few that nothing checks.
- **Merge safely**: Before a change lands, Braid checks it against the decisions already on main, and stops one that quietly undoes another.
- **Trace any line to its reason**: Ask why a line exists, in review or in production. Braid answers with the decision behind it and the request that started it.
- **Give your agents better context**: Your agents read the decisions behind the code before they change it. They skip the approaches your team already set aside.

## Know what your agent did. Decide what's next.

How it works. Once the work is committed, ask your agent to reconstruct the intent. Build a working model of its direction and decisions. Then fix a bad call, hand it to a reviewer, or pick it up next week. The examples are from a real braid of the [BrewGo](https://github.com/braidkit/brewgo) sample app: 9 steps and 6 decisions.

### See every choice, and the roads not taken.

Decisions. Each decision shows the question the agent faced, the approach it picked, what it rejected and why, and the checks behind it. Inspect code jumps to the lines that decision shaped.

Example: D5, "Open and close SQLite connections per list call".

- Question: How should the SQLite repository manage database connections during list calls?
- Covered by: step 09, "Test SQLite order repository". Tests passed.
- Chosen approach: **Open and close per list call.** Each read sees current orders, and no database file stays open after the list returns.
- Other approach considered: **Keep one connection open.** Not chosen: it would leave the database file open.

### Read the work in the order it happened.

Steps. Each step says what the agent did, the decision that drove it, and the files it touched. Open a file to land on the exact lines.

Example: step 08, "Add SQLite order repository", carries out decisions D5 and D6. The SQLite order repository opens the database per list call, reads order payloads, and closes the file after returning rows. It changed `src/backend/app.js`.

### Know which agent did what.

Workstreams. When your agent splits the work, each subagent gets a workstream: the job it was given, the model that ran it, and the files it changed. Open the trace when you want the receipts.

Example:

- W01, BrewGo admin analytics: main agent, Claude Opus 5.5.
- W02, SQLite order repository: subagent, Claude Sonnet 5.5. Intent: read current orders from BrewGo's SQLite database on each list call, without writing to it. Files: `src/backend/app.js` (+25), `test/backend-analytics.test.js` (+127).
- W03, Admin analytics view: subagent, Claude Sonnet 5.5.

### See the shape of the change.

Diagrams. Diagrams map the components the change touched, how they call each other, and which calls a decision shaped. Select a component to get to its files.

Example: the new SQLite order repository reads BrewGo's SQLite orders and supplies the existing analytics calculator. The component diagram shows four components: the analytics handler, the SQLite order repository (decisions D5 and D6), the analytics calculator, and the BrewGo SQLite database, which the change does not alter.

### Settle the decision together.

Multiplayer. Your team comments on the decision itself, next to the approaches and the reasons. When you agree on a fix, hand it to your agent. Today, share the intent on your pull request for teammates to read.

### Watch a teammate review the decisions.

A film without sound: Alex builds a best sellers page for BrewGo with a coding agent and asks for a review. Braid packs the session for the team. Priya opens the intent in her own agent, reads each decision and the approaches the agents considered, and disagrees with one decision. [Watch the film](https://braidkit.io/videos/braid-handoff-film.mp4).

## Stop cognitive surrender to your agents.

- [Install Braid](https://docs.braidkit.io/quickstart/#1-install-braid). For macOS. Works with Claude Code and Codex.
- [Setup guide for your agent](https://docs.braidkit.io/quickstart.agent.md)

## More

- [Docs](https://docs.braidkit.io/)
- [FAQ](https://braidkit.io/faq.md)
- [Discord](https://discord.gg/gCTB7mC3Hq)
- [Email](mailto:hello@braidkit.io)