01 — The problem
Workspace state is fragmented across repositories.
Git answers questions about an individual repository precisely. Across many independent projects, however, those answers remain distributed.
Current branch, working tree, upstream, history, refs, and divergence are local properties of each repository. As the number of projects grows, simple questions start requiring manual navigation, custom scripts, or human memory.
Which repositories exist on this machine? Which ones have pending local work? Which worktrees belong to the same repository? Which observations still represent current state? Where did an inspection fail?
Git is not the problem. These questions belong to a layer above it.
02 — The solution
A persistent, observable inventory of the local workspace.
BullSaddle builds its own representation of the Git environment without becoming authoritative over the repositories themselves.
It discovers repositories and worktrees, preserves their identities, records observations, and allows the consolidated workspace state to be queried later.
Git remains authoritative for repository state. BullSaddle maintains the operational view across the set.
This separation makes it possible to observe many repositories without introducing another version-control system, another repository format, or a second semantics for commits and branches.
03 — How it works
Discover. Observe. Query.
The operating model keeps inventory, observation, and reads of previously recorded state explicitly separate.
discover identifies repositories under the requested roots and updates the local inventory. refresh observes their Git state and records new observations. Queries such as repos, inspect, and overview read what has already been discovered and observed.
Discovery and observation do not happen silently during a query. Observation age remains explicit, and a failure in one path, worktree, or Git process can be recorded without turning the entire workspace into one indivisible operation.
The result is a clear distinction between what exists, what was observed, and when that observation was produced.
04 — What becomes visible
The workspace becomes a queryable entity.
BullSaddle brings together information that would otherwise need to be inspected repository by repository.
The inventory distinguishes repositories, worktrees, and physical locations. Observations can record working tree state, branch and HEAD, upstream relationships, local/remote divergence, diagnostics, and freshness. Queries can also produce structured output for integration with other tools and automation.
On top of that observed state, BullSaddle can produce deterministic advisories without presenting heuristics as facts and without requiring artificial intelligence to understand the workspace.
05 — Boundaries
Observing Git does not mean controlling Git.
BullSaddle is read-only with respect to the repositories it observes.
Discovery, refresh, and queries do not create commits, branches, refs, worktrees, or stashes, and do not modify the index or working-tree files. They also do not implicitly run fetch, pull, push, or clone.
The tool may update only its own persistent state — inventory, observations, and the metadata needed to represent the workspace.
The boundary is simple: Git controls the repository; BullSaddle observes the environment around it.
06 — Project
Local-first engineering with Git remaining at the center.
BullSaddle is developed in Rust by Orion Impact and distributed under the Apache License 2.0. The current public version is 0.2.0; the currently certified native target is x86_64-unknown-linux-gnu.
The public repository contains source code, technical documentation, build instructions, CLI reference, and the details needed to use or study the implementation.