Start here
Install it, name yourself, then ask what needs your attention.
Install
Homebrew is the shortest path. The standalone installer verifies the published checksum before replacing a binary.
Set your identity
Baari uses an alias to decide which thread replies belong to you.
Run it inside a repository
The repository joins your machine-local registry automatically. No account or hosted workspace is required.
Homebrew
brew install nauman/tap/baari
Standalone installer
curl --proto '=https' --tlsv1.2 -fsSL https://nauman.github.io/baari/install.sh | sh
First run
baari identity set <your-alias> baari status
Coordination
A small answer to a costly question: who owes what?
Baari reads living Markdown threads from every registered repository and presents them through one stable vocabulary. Use the human-readable output in a terminal or request bounded JSON when an agent should consume only the latest context.
baari status
Show work owed by you, work waiting on others, closed ownership, and parked conversations across repositories.
baari next
Return only the replies owed by your resolved identity.
baari thread list · show · lint-roster
Find conversations, read a bounded number of entries as Markdown or JSON, and catch owners missing from the repository roster.
baari registry
List known repositories, prune missing paths, or explicitly ignore repositories that should stay outside the cross-repo view.
Baari reads canonical threads; it does not invent a second conversation format. Thread reply, park, resume, and close commands are not part of the current release.
Delivery sequences
One registry becomes both an agent-readable plan and a beautiful human view.
A repository owns one docs/sequence.yml. Global waves describe the shared delivery order; substantial programs can add dense subwaves underneath them. Specs are assigned to those waves instead of being copied into another roadmap.
Define a global wave and a program subwave
baari docs sequence wave define W1 --title "Build" baari docs sequence wave define W1.1 \ --title "Commercial foundations" \ --under W1 \ --program commercial \ --plan plans/commercial.md
Assign a spec, then generate global or bounded views
baari docs sequence assign specs/031-capabilities.md --to W1.1 baari docs sequence build baari docs sequence build \ --program commercial \ --output docs/plans/commercial/00-delivery-sequence
The default build writes docs/plans/00-delivery-sequence.md and docs/plans/00-delivery-sequence.html. A program filter keeps its parent and dependency context and requires an explicit output path. Every result is a projection; sequence.yml remains the source.
Documentation and guardrails
Scaffold the convention once. Then make drift visible.
baari docs init · docs doctor
Create the canonical docs tree from embedded templates, then report structural drift. Add --strict when findings should fail CI.
baari adr list · adr check
Read the decision register and catch malformed records, invalid status values, or index drift.
baari ci tree · ci run
Inspect guard layers and run the repository’s declared native gate. Stable JSON and strict exit behavior make it usable in automation.
baari explain
Explain the delivery model from workbench and requirements through architecture, specs, sequence, and status.
baari contract
Emit the versioned JSON command ledger that drives the virtual terminal above and travels with every release.
baari work · ready · verify · ledger
Combine local groups, tasks and bugs with Markdown owner pointers and named Jira/Linear connections. Ready plans bind their Architecture and Design sources; explicit acceptance checks produce revision-bound evidence. The ledger keeps work state, verified acceptance and Git delivery separate.
baari release · release reconcile · loop run
Run native release gates and reconcile publication outcomes. Hand a ready plan to an explicitly configured external runner; runner success alone does not prove acceptance.
Safe local work
Shared checkouts need explicit boundaries, not optimistic cleanup.
baari worktree list · prune
Inspect every checkout and remove only worktrees where nothing would be lost. Pruning is a dry run until --confirm.
baari testdb list · prepare · prune
Give each checkout its own test database, prepare the current one, and identify databases whose worktree no longer exists.
baari doctor
Validate the machine registry, resolved identity, repository markers, and roster before work starts.
Behavior you can reason about
Local-first does not mean pretending every command is read-only.
| Behavior | Commands | Boundary |
|---|---|---|
| Read | status, next, whoami, doctor, contract, thread reads, docs doctor, ADR checks, CI tree |
Read local repository and machine state. |
| Local state | identity, registry, thread scaffold |
Write explicit configuration or scaffolding under your user-owned Baari state. |
| Repository | docs init, sequence wave/assign/build |
Write named documentation artifacts. Existing docs are replaced only when the command explicitly allows it. |
| Workspace | worktree prune, testdb prepare, testdb prune |
Potentially mutating operations are explicit; prune commands preview before confirmation. |
| Network | upgrade, auth, configured work, release, docs publish |
Network operations run when explicitly selected. Upgrade checks releases; auth, tracker work and publication use their configured providers. |
There is no Baari account or telemetry client. Local coordination and documentation inspection use files on your machine. Explicit provider and publication commands use their configured network services; the visual companion starts a local server only when requested and provides a stop command.
Optional authenticated canon
Teams can layer private guidance on top of the embedded generic rules.
A repository may name an additional documentation source in .baari.yml. baari auth status, auth init, and auth sync use the existing gh login; Baari stores no GitHub token. Without access, the embedded generic set remains available.
Planned, not shipped
The next layer is active coordination. It is not part of the current binary.
Local dashboard
A live operator view over the same registry and thread state.
Event-driven watch
React to relevant changes without a wasteful polling loop.
Agent dispatch
Start, address, and stop individual agent processes through an explicit operator boundary.
Program-filtered sequence projections and explicit Jira/Linear work connections are shipped. Roadmap items are not installation promises.
Install and upgrade
Check before upgrading
baari upgrade --check
Upgrade a standalone install
baari upgrade
Upgrade a Homebrew install
brew upgrade nauman/tap/baari
The public repository contains the landing page, installer, and checksummed release binaries. Source code is not published in that repository.