Understand Balladeer

Balladeer helps your team ship faster with agentic code review grounded in remembered product intent. After your coding agent pushes, an independent agent reviews the change against the behavior your team has agreed to keep. It tries to reproduce regressions and gives your agent the reproduction and repair instructions. Tests committed with those repairs strengthen your ordinary suite for future changes.

Code review that remembers what matters#

A reasonable code change can break a commitment nobody explained to the agent making it. Balladeer preserves those commitments as promises and carries relevant intent into the next change. The review uses that meaning to look for behavioral regressions in the affected code.

A broken verdict needs a reproduction that fails on the changed commit and passes on its base. The review checks selected agreed promises and exercises concrete cases; a pass is not proof that all code is correct. It uses your existing Claude Code or Codex login, with no separate model API key or sealed CI qualification required. See agentic code review on push.

What is a promise?#

A promise describes behavior, who depends on it, when it applies, and what would count as breaking it. A useful promise earns its place in two ways:

• Someone new to the code could plausibly break it during reasonable work because the rule is not evident where it would break. It may have broken before or sit far from the code being changed.
• A check can tell keeping it from breaking it, catching the named failure rather than unrelated changes.

For example:

An invited teammate can join an existing workspace without connecting another repository.

The joining flow and the repository-enrollment flow can change independently. A check can establish whether joining now requires another repository or modifies CI. That makes the commitment useful to carry between people and agents.

A style preference, an implementation choice, or a hint to another model is not automatically a promise. An ordinary test or an AGENTS.md instruction may be enough. “Make it fast” needs an actual measurement and a defined threshold before a check can decide it.

How does it work?#

1. Preserve intent during the work. Your agent offers a specific commitment in your words. A yes or a generic go-ahead to that offer records it; silence does not. You can also ask to record it directly.
2. Carry it into the next change. Relevant recorded intent is already useful, with its recorder and lack of agreement shown. A named owner can agree its meaning in the conversation; no separate review meeting is needed.
3. Review the code after the push. Setup installs hooks for Claude Code and Codex. Using your existing agent login, the check identifies agreed promises whose code the change touches and tries to break them. It does not need a sealed CI verifier or a separate model API key.
4. Turn a reproduced break into a lasting test. The pushing agent receives the reproduction and repair instructions. A regression test committed with the fix becomes part of your ordinary suite and CI.

See capture, agentic code review on push, and making a change.

Where does agreement fit?#

Recording intent, agreeing its meaning, and checking it are different things. Recorded intent can guide work before formal agreement; it is labelled not agreed, never Protected. Agreement establishes the behavior the named owner intends to preserve and makes it eligible for the push check.

You can agree in your own connected agent conversation. The agent carries your actual words and the exact proposal you saw. Changing agreed meaning still needs fresh agreement. The agent cannot decide that a regression was an intentional product change.

What does Balladeer add to existing tests?#

Your suite checks the cases already written. Balladeer also gives agents the intent behind the behavior and agentic code review that tries to reproduce regressions in the change. When that attempt reproduces a failure, the team keeps a test for it in its own suite. Future runs of that test need no model and no Balladeer service.

A separate sealed CI verifier can qualify a promise for the hosted Protected status. That is an additional evidence path, described in protect your first behavior. It is not a prerequisite for the agentic push check.

What do results establish?#

A push check reports kept, broken, or could not tell for the promises it checked. Broken needs a reproduction that fails on the changed commit and passes on the base, verified by running it both ways. Kept means the passing cases were exercised; it does not prove every possible input or production behavior.

The push check does not grant Protected status. A qualified sealed verifier and eligible CI evidence establish that separate status. A local pass, a passing PR, and a deployed customer outcome are different evidence.

Where does the work happen?#

Agents and checks run in your environment. Balladeer stores meaning, ownership, bounded results, and paths and symbol names tying promises to code. Source, tests, reproductions, logs, prompts, and raw agent transcripts stay out of the hosted store. Your local headless agent uses its model provider under your existing login. See data and permissions.

Does Balladeer block merges?#

By default the agentic check reports after the push and never holds it. Blocking before a push is an explicit repository choice. Your normal tests and branch-protection rules determine whether a pull request can merge. See agentic code review on push.

Next: Set up Balladeer.