rebar

An event-sourced, git-backed ticket store + Jira reconciler built for agent swarms — one store, exposed as a Python library, a CLI, and an MCP server.

• Three surfaces, one store — drive rebar as a CLI (rebar), a Python library (import rebar), or an MCP server (rebar-mcp).
• The tracker lives in the repo — tickets are an append-only event log on a tickets git branch; no database, no daemon, and it travels with every clone.
• Built for parallel agents — atomic claims, convergent merges, and provenance links let many agents and sessions write at once without lost work.
• Optional LLM gates — review a ticket's plan before work, its completion before close, and its code before it merges.
• Bidirectional Jira sync — a level-triggered reconciler keeps tickets and Jira in step, so teammates stay in the loop.
• Dogfooded through two independent gates — every change to rebar's own main must pass an LLM code review and CI, on Gerrit, before it lands.

Install

pipx install nava-rebar          # the `rebar` CLI (add [mcp] / [agents] for those extras)
brew install navapbc/rebar/rebar # or via Homebrew

Quickstart

Run one ticket end-to-end with the CLI or the Python library; the JSON block is the MCP server config so agents can drive the same loop over MCP. rebar --help (and rebar <command> --help) is the authoritative command reference.

# CLI: one ticket through init -> create -> ready -> claim -> close
rebar init
tid=$(rebar create task "Add a login page" -o json | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')
rebar ready                                              # lists it as ready to work
rebar claim "$tid"                                       # open -> in_progress
rebar transition "$tid" in_progress closed              # in_progress -> closed

import rebar                                            # the same loop via the Python library
tid = rebar.create_ticket("task", "Add a login page")
rebar.claim(tid)
rebar.transition(tid, "in_progress", "closed")

{ "mcpServers": { "rebar": { "command": "uvx", "args": ["--from", "nava-rebar[mcp]", "rebar-mcp"] } } }

That's the whole loop — init → create → ready → claim → close. The CLI and Python blocks each drive one ticket end-to-end (the same id threaded through every step, no hard-coded id); the JSON is the MCP server config — add it to your client so an agent can run the same loop via the MCP tools. State is shared through the repo so many agents (and teammates via Jira) coordinate without stepping on each other.

How it works

rebar stores tickets as an append-only event log on a dedicated tickets git orphan branch (worktree at .tickets-tracker/); ticket state is computed by replaying events, and every write auto-commits and pushes so the store is shared immediately. A level-triggered reconciler bidirectionally syncs tickets with Jira. The branch name and worktree dir are configurable (tracker.branch / tracker.dir — see Configuration). Reads stay sub-second into the thousands of tickets; for measured numbers and git-growth expectations see docs/scale-envelope.md.

Documentation lives under docs/ — start with the docs index (grouped by audience: user / operator / contributor / agent) or the day-to-day user guide.

Why rebar

If you run coding agents against a repo, you eventually want to run several at once — and the moment you do, they need a shared place to coordinate. Most trackers weren't built for that:

• They're heavy. A daemon to babysit or a local database to keep running, with dependencies thick enough that a routine upgrade can break your work tracking across machines.
• They don't travel with the code. State lives outside the repo, so a fresh clone doesn't come with its tickets.
• They fight your git history. A tracker that writes to your working branch tangles ticket churn into your source-code commits.
• They have no concurrency story. Nothing stops two agents from claiming the same work or clobbering each other's state, and concurrent edits produce merge conflicts you resolve by hand — or lose.
• They buckle at scale. Speed and usability fall off past a few hundred tickets.

rebar's answer is to make the tracker part of the repo. Tickets are an append-only event log on a dedicated tickets orphan branch (linked in through a gitignored worktree); current state is a fast, deterministic replay of that log. That single decision pays off across the board:

• Zero infrastructure, fully portable. No database, no daemon — just git and a lightweight Python install. Clone the repo and the tracker comes with it.
• No commit interference. Ticket events live on their own branch and never touch your source history. Every write auto-commits and auto-pushes, so activity is shared in real time.
• Concurrency by design. Each event gets a globally-unique filename, so parallel writes merge as a clean union, and the rare conflicting fork resolves deterministically — every clone converges with no lost data. claim is an atomic, optimistic-concurrency primitive: agents grab work without stepping on each other.
• Built to scale. The event log plus cached replay stays fast as tickets grow.

On top of that foundation, rebar adds what parallel agent work actually needs:

• Bidirectional Jira sync — agents work in rebar, teammates work in Jira, and a level-triggered reconciler keeps the two in step. To run it automatically in CI, see docs/jira-sync-setup.md (the GitHub Actions reconcile-bridge + heartbeat-canary setup).
• Conflict-aware scheduling — tickets record their file impact, so next-batch hands parallel agents work that won't collide on the same files.
• Scratch space — an invisible per-ticket channel for subagents to pass notes to one another.
• Structural quality gates — clarity, acceptance-criteria, dispatch-readiness, and repo-wide health checks keep work dispatch-ready.
• LLM review gates (optional). Review an agent's plan before work starts, its completion before the ticket closes, and its code before it merges. Plan-review and code-review share one four-pass kernel. A finder cites evidence, a separate verifier tests each claim with atomic yes or no questions, and deterministic policy decides what blocks. A passing plan or completion review records an operation certificate as a DSSE envelope. The envelope carries an SSHSIG signature over its PAE bytes, produced with the signing environment's Ed25519 key. The certificate names that environment as its principal. The result is a machine-checkable process record for the reviewed work.
• Provenance links — discovered_from ties emergent work back to the ticket that surfaced it.
• One store, three interfaces — drive it from the CLI, a Python library, or the MCP server.

Requirements

System prerequisites:

• Python ≥ 3.11
• git is a runtime prerequisite because the store uses a Git orphan branch and worktree. The runtime engine uses in-process Python and does not require bash or jq.
• Git 2.38 or newer is required for development, tests, and CI. The floor is declared in .github/git-version-floor.txt. The test suite and CI fail when Git is below that floor.
• Deployments that use the optional S3 repair path require Git 2.38 or newer because that path invokes git merge-tree --write-tree.
• No external lock binary is required. Write serialization uses a two-window lock built entirely from the Python standard library — a fcntl.flock(LOCK_EX) advisory lock plus an atomic mkdir lock (src/rebar/_store/lock.py) — so there is no dependency on util-linux's flock binary (or any other external tool). The mkdir window keeps mutual exclusion holding even where fcntl.flock is unreliable (e.g. some network filesystems).
• acli (Atlassian CLI) — a required external binary for the Jira Cloud reconciliation/bridge path: every bridge/reconcile Cloud mutation shells out to it, so it must be installed on PATH (install pointer: docs/jira-sync-setup.md). The [jira-datacenter] Data Center path does not need it — it uses the jira Python library.

Python dependencies. A base install (pip install nava-rebar) provides the rebar CLI, the import rebar library, and the lean workflow engine. It installs pyyaml>=6 for the workflow DSL loader, jsonschema>=4.18 for schema registry and workflow input and output validation, and referencing>=0.30 for JSON Schema $ref resolution. The engine core and reconciler otherwise use the Python standard library. All other dependencies are optional extras that are imported lazily to keep the base installation light. CI verifies this boundary.